Scribble: The Racket Documentation Tool
Scribble is a collection of tools for creating prose
documents—
This document is itself written using Scribble. You can see its source at https://github.com/racket/scribble/tree/master/scribble-doc/scribblings/scribble, starting with the "scribble.scrbl" file.
4.2.3 Documenting Forms, Functions, Structure Types, and Values |
1 Getting Started
No matter what you want to do with Scribble, it’s best to start by generating a few simple HTML and/or PDF documents. This chapter steps you through the basics, and it ends in Next Steps with goal-specific advice on how to continue.
1.1 A First Example
Create a file "mouse.scrbl" with this content:
#lang scribble/base @title{On the Cookie-Eating Habits of Mice} If you give a mouse a cookie, he's going to ask for a glass of milk.
The first line’s #lang scribble/base indicates that the file implements a Scribble document. The document starts in “text mode,” and the @ character escapes to operators like title, where the curly braces return to text mode for the arguments to the operator. The rest is document content.
Now run the scribble command-line program, specifying a mode for the kind of document that you want as output:
- Runscribble mouse.scrblto generate HTML as "mouse.html". You may notice that the apostrophe in “he’s” turned into a curly apostrophe.
- Runscribble --htmls mouse.scrblto generate HTML as "mouse/index.html". Sub-sections (which we add next) will appear as separate HTML files in the "mouse" directory.
- Runscribble --pdf mouse.scrblto generate PDF as "mouse.pdf". This will work only if you have pdflatex installed. If you’d like to see the intermediate Latex, tryscribble --latex mouse.scrblto generate "mouse.tex".
See Running scribble for more information on the scribble command-line tool.
1.2 Multiple Sections
Add more text to "mouse.scrbl" so that it looks like this:
#lang scribble/base @title{On the Cookie-Eating Habits of Mice} If you give a mouse a cookie, he's going to ask for a glass of milk. @section{The Consequences of Milk} That ``squeak'' was the mouse asking for milk. Let's suppose that you give him some in a big glass. He's a small mouse. The glass is too big---way too big. So, he'll probably ask you for a straw. You might as well give it to him. @section{Not the Last Straw} For now, to handle the milk moustache, it's enough to give him a napkin. But it doesn't end there... oh, no.
Now, after the first paragraph of the paper, we have two sub-sections, each created by calling section to generate a sub-section declaration. The first sub-section has two paragraphs. The second section, as initiated by the result of the second section call, has a single paragraph.
Run the scribble command(s) from A First Example again. You may notice the curly double-quotes in the output, and the --- turned into an em dash.
1.3 Splitting the Document Source
As a document grows larger, it’s better to split sections into separate source files. The include-section operation incorporates a document defined by a ".scrbl" file into a larger document.
To split the example document into multiple files, change "mouse.scrbl" to just
#lang scribble/base @title{On the Cookie-Eating Habits of Mice} If you give a mouse a cookie, he's going to ask for a glass of milk. @include-section["milk.scrbl"] @include-section["straw.scrbl"]
Create "milk.scrbl" and "straw.scrbl" in the same directory as "mouse.scrbl". In "milk.scrbl", put
#lang scribble/base @title{The Consequences of Milk} That ``squeak'' was the mouse asking for milk...
and in "straw.scrbl", put
#lang scribble/base @title{Not the Last Straw} For now, to handle the milk moustache, ...
Notice that the new files both start with #lang, like the original document, and the sections from the original document become titles in the new documents. Both "milk.scrbl" and "straw.scrbl" are documents in their own right with their own titles, and they can be individually rendered using scribble. Running scribble on "mouse.scrbl", meanwhile, incorporates the smaller documents into one document that is the same as before.
1.4 Document Styles
Scribble currently supports only one form of HTML output. You can replace the "scribble.css" file for the generated pages, and that’s about it. (We expect to add more styles in the future.)
For Latex-based PDF output, Scribble includes support for
multiple page-layout configurations. The "mouse.scrbl"
example so far uses the default Latex style. If you plan on submitting
the paper to a workshop on programming languages, then—
#lang scribble/acmart
If you’re instead working toward Racket library documentation, try changing the first line to
#lang scribble/manual
which produces output with a separate title page, initial content on that page (intended as a brief orientation to the document), and top-level sections turned into chapters that each start on a new page. If you have split the document into multiple files, the first line of the main document file determines the output format.
Using scribble/acmart or
scribble/manual does not change the rendered HTML for
a document—
#lang scribble/acmart @title{On the Cookie-Eating Habits of Mice} @abstract{If you give a mouse a cookie, he's going to ask for a glass of milk.} @section{The Consequences of Milk} ....
When rendered as HTML, the abstract shows up as an inset paragraph. If you try to use abstract with the scribble/base or scribble/manual language, then you get an error, because abstract is not defined.
When a document is implemented across multiple files, changing the language of the main document can set the style for all of the parts, but it does not introduce bindings into the other part files. For example, if you change the language of "mouse.scrbl" to scribble/acmart, then abstract becomes available in "mouse.scrbl" but not in "milk.scrbl" or "straw.scrbl". In other words, operator names are lexically scoped.
1.5 More Functions
The scribble/base language provides a collection of basic operations (both scribble/acmart and scribble/manual are supersets of scribble/base). Many of the operations are style variations that you can apply to text:
He's a @smaller{small mouse}. The glass is too @larger{big}---@bold{way @larger{too @larger{big}}}. So, he'll @italic{probably} ask you for a straw.
which renders as
He’s a small mouse. The glass is too big—
way too big. So, he’ll probably ask you for a straw.
As you would expect, calls to functions like smaller, larger, and bold can be nested in other calls. They can also be nested within calls to title or section:
@section{@italic{Not} the Last Straw}
1.5.1 Centering
The centered operation centers a flow of text:
If a mouse eats all your cookies, put up a sign that says @centered{ @bold{Cookies Wanted} @italic{Chocolate chip preferred!} } and see if anyone brings you more.
which renders as
If a mouse eats all your cookies, put up a sign that saysCookies Wanted
Chocolate chip preferred!
and see if anyone brings you more.
1.5.2 Margin Notes
The margin-note operation is used in a similar way, but the rendered text is moved to the margins. If you use margin-note, then the content shows up over here.
1.5.3 Itemizations
The itemlist operation creates a sequence of bulleted text, where the item operation groups text to appear in a single bullet. The itemlist operation is different from the others that we have seen before, because it only accepts values produced by item instead of arbitrary text. This difference is reflected in the use of [...] for the arguments to itemlist instead of {...}:
@centered{@bold{Notice to Mice}} @itemlist[@item{We have cookies for you.} @item{If you want to eat a cookie, you must bring your own straw.}]
which renders as
Notice to Mice
We have cookies for you.
If you want to eat a cookie, you must bring your own straw.
1.5.4 Tables
The tabular function takes a list of lists to organize into a two-dimensional table. By default, no spacing is added between columns, so supply a #:sep argument to act as a column separator. For example,
@tabular[#:sep @hspace[1] (list (list @bold{Animal} @bold{Food}) (list "mouse" "cookie") (list "moose" "muffin"))]
renders as
Animal
Food
mouse
cookie
moose
muffin
1.6 Text Mode vs. Racket Mode for Arguments
When [...] surrounds the arguments of an operation, the argument expressions are in Racket mode rather than text mode. Even in Racket mode, @ can be used to apply operations; once the @ syntax is enabled through a language like scribble/base (as opposed to racket), it behaves the same in both Racket mode and text mode.
One advantage of using Racket mode for the arguments to itemlist is that we can pass a keyword-tagged optional argument to itemlist. In particular, if you want a list with numbers instead of bullets, supply the 'ordered style to itemlist using the #:style keyword:
@itemlist[#:style 'ordered @item{Eat cookie.} @item{Drink milk.} @item{Wipe mouth.} @item{...}]
An operation doesn’t care whether it’s used with [...] or {...}. Roughly, {...} forms an argument that is a string. (Only roughly, though. Newlines or uses of @ within {...} complicate the picture, and we’ll get back to that soon.) So,
@italic{Yummy!}
is equivalent to
@italic["Yummy!"]
which is equivalent to the Racket expression
(italic "Yummy!")
These equivalences explain why Scribble functions are documented in Racket notation. If you’re reading this in HTML format, you can click italic above to access its documentation. The documentation won’t completely make sense, yet, but it will by the end of this chapter.
What if you want to provide arguments in text mode, but you also want to supply other optional arguments? You can use both [...] and {...} for an operation, as long as the [...] is first, and as long as no characters separate the closing ] from the opening {. For example, calling italic is the same as using elem with the 'italic style:
@elem[#:style 'italic]{Yummy!}
You can also omit both [...] and {...}. In that case, the Racket expression after @ is used directly instead of applied as an operation. For example,
1 plus 2 is @(number->string (+ 1 2)).
renders as
1 plus 2 is 3.
The call to number->string is needed because a naked number is not valid as document content.
1.7 @ Syntax Basics
The @ notation provided by Scribble is just another way of writing Racket expressions. Scribble documents could be constructed using normal Racket notation, without using @ at all, but that would be inconvenient for most purposes. The @ notation makes dealing with textual content much easier.
Whether in text mode or Racket mode, @ in a document provides an escape to Racket mode. The basic syntax of @ is
@ ‹cmd› [ ‹datum›* ] { ‹text-body› }
where all three parts after @ are optional, but at least one must be present. No spaces are allowed between
@ and ‹cmd›, [, or {
‹cmd› and [ or {; or
] and {.
A ‹cmd› or ‹datum› is normal Racket notation, while a ‹text-body› is itself in text mode. A ‹cmd› obviously must not start with [ or {, even though Racket forms could otherwise start with those characters.
The expansion of just @‹cmd› into Racket code is
‹cmd›
When either [ ] or { } are used, the expansion is
(‹cmd› ‹datum›* ‹parsed-body›*)
where ‹parsed-body›* is the parse result of the ‹text-body›. The ‹parsed-body›* part often turns out to be a sequence of Racket strings.
In practice, the ‹cmd› is normally a Racket identifier that is bound to a procedure or syntactic form. If the procedure or form expects further text to typeset, then {...} supplies the text. If the form expects other data, typically [...] is used to surround Racket arguments, instead. Even if an operation’s argument is a string, if the string is not used as content text (but instead used as, say, a hyperlink label), then the string is typically provided through [...] instead of {...}. Sometimes, both [...] and {...} are used, where the former surround Racket arguments that precede text to typeset. Finally, if a form is a purely Racket-level form with no typeset result, such as a require to import more operations, then typically just @ is used.
For example the text-mode stream
@(require scriblib/figure) @section[#:tag "poetry"]{Of Mice and Cookies} See @secref["milk"]. @section[#:tag "milk"]{@italic{Important} Milk Supplies} @figure["straw" @elem{A straw}]{@image["straw.png"]}
is equivalent to the Racket-mode sequence
(require scriblib/figure) "\n" "\n" (section #:tag "poetry" "Of Mice and Cookies") "\n" "See " (secref "milk") "." "\n" "\n" (section #:tag "milk" (italic "Important") " Milk Supplies") "\n" (figure "straw" (elem "A straw") (image "straw.png")) "\n"
Besides showing how different argument conventions are used for
different operations, the above example illustrates how whitespace is
preserved in the Racket form of a text-mode stream—
In addition to its role for command, a @ can be followed by ; to start a comment. If the character after ; is {, then the comment runs until a matching }, otherwise the comment runs until the end-of-line:
@;{ ‹comment› } @; ‹line-comment›
For more information on the syntax of @, see @ Syntax. The full syntax includes a few more details, such as brackets like |{...}| for text-mode arguments while disabling @ between the brackets.
1.8 Decoding Sequences
In a document that starts #lang scribble/base, the top level is a text-mode stream, just like the ‹text-body› in a @ form. As illustrated in the previous section, such a top-level sequence corresponds to a mixture of Racket-mode strings and operation applications. There’s an implicit operation, decode, that wraps the whole document to consume this mixture of strings and other values and turn them into a document description.
The decode operation implements flow decoding, which takes a document stream and breaks it up into sections and paragraphs. Blank lines delimit paragraphs, and the results of operations like title and section generate “here’s the title” or “a new section starts here” declarations that are recognized by decode.
A different but related content decoding takes place within a paragraph or section title. Content decoding is responsible for converting --- to an em dash or for converting " and ' to suitable curly quotes.
The decoding process for document’s stream is ultimately determined by the #lang line that starts the document. The scribble/base, scribble/manual, and scribble/acmart languages all use the same decode operation. The scribble/text language, however, acts more like a plain-text generator and preprocessor, and it does not perform any such decoding rules. (For more on scribble/text, see Scribble as Preprocessor.)
More precisely, languages like scribble/base apply decode only after lifting out all definitions and imports from the document stream.
When the flow decoder is used, after it breaks the input stream into paragraphs, it applies content decoding to strings within the paragraph. When content is wrapped with an operation, however, content decoding does not apply automatically. An operation is responsible for calling a content or flow decoder as it sees fit. Most operations call the decoder; for example, italic, bold, smaller, etc., all decode their arguments. Similarly, title and section decode the given content for the title or section name. The literal and verbatim operators, however, do not decode the given strings. For example,
@verbatim{---}
renders as
---
Don’t confuse decoding with the expansion of @ notation. The source form
@verbatim{@(number->string (+ 1 2))}
renders as
3
because the source is equivalent to
(verbatim (number->string (+ 1 2)))
where (number->string (+ 1 2)) is evaluated to produce the argument to verbatim. The |{...}| style of brackets is often used with verbatim, because |{...}| disables @ notation for arguments. For example,
@verbatim|{@(number->string (+ 1 2))}|
renders as
@(number->string (+ 1 2))
1.9 Pictures
Any value that is convertable to an image can be used directly within a Scribble document. Functions from the pict and 2htdp/image libraries, for example, generate images. For example,
@(require pict) This cookie has lost its chocolate chips: @(colorize (filled-ellipse 40 40) "beige").
renders as
This cookie has lost its chocolate chips:
.
1.10 Next Steps
If your immediate goal is to document a Racket library or write literate programs, skip to Getting Started with Documentation, and then go back to @ Syntax and other chapters.
If you are more interested in producing documents unrelated to Racket, continue with @ Syntax and then High-Level Scribble API. Move on to Low-Level Scribble API when you need more power.
If you are interested in text generation and preprocessing, continue with @ Syntax, but then switch to Scribble as Preprocessor.
2 @ Syntax
The Scribble @ notation is designed to be a convenient facility for free-form text in Racket code, where “@” was chosen as one of the least-used characters in existing Racket code. An @-expression is simply an S-expression in disguise.
Typically, @ notation is enabled through scribble/base or similar languages, but you can also add @ notation to an S-expression-based language using the at-exp meta-language. For example,
#lang at-exp racket |
(define v '@op{str}) |
is equivalent to
#lang racket (define v '(op "str"))
Using #lang at-exp racket is probably the easiest way to try the examples in this chapter.
2.1 The Scribble Syntax at a Glance
To review @ Syntax Basics, the concrete syntax of @-forms is roughly
@ ‹cmd› [ ‹datum›* ] { ‹text-body›* }
where all three parts after @ are optional, but at least one should be present. (Spaces are not allowed between the three parts.) Roughly, a form matching the above grammar is read as
(‹cmd› ‹datum›* ‹parsed-body›*)
where ‹parsed-body› is the translation of each ‹text-body› in the input. Thus, the initial ‹cmd› determines the Racket code that the input is translated into. The common case is when ‹cmd› is a Racket identifier, which reads as a plain Racket form, with datum arguments and/or string arguments.
Here is one example:
| @foo{blah blah blah} | reads as | (foo "blah blah blah") |
The example shows how an input syntax is read as Racket syntax, not what it evaluates to. If you want to see the translation of an example into S-expression form, add a quote in front of it in a #lang at-exp racket module. For example, running
#lang at-exp racket |
'@foo{blah blah blah} |
in DrRacket prints the output
(foo "blah blah blah")
while omitting the quote
#lang at-exp racket |
@foo{blah blah blah} |
triggers a syntax error because foo is not bound, and
#lang at-exp racket |
(define (foo str) (printf "He wrote ~s.\n" str)) |
@foo{blah blah blah} |
prints the output
He wrote "blah blah blah".
Here are more examples of @-forms:
| @foo{blah "blah" (`blah'?)} | reads as | (foo "blah \"blah\" (`blah'?)") | |||||||
| ||||||||||
| @foo[1 2]{3 4} | reads as | (foo 1 2 "3 4") | |||||||
| ||||||||||
| @foo[1 2 3 4] | reads as | (foo 1 2 3 4) | |||||||
| ||||||||||
| @foo[#:width 2]{blah blah} | reads as | (foo #:width 2 "blah blah") | |||||||
| ||||||||||
|
| reads as |
| |||||||
| ||||||||||
|
| reads as |
|
As seen in the last example, multiple lines and the newlines that separate them are parsed to multiple Racket strings. More generally, a ‹text-body› is made of text, newlines, and nested @-forms, where the syntax for @-forms is the same whether it’s in a ‹text-body› context as in a Racket context. A ‹text-body› that isn’t an @-form is converted to a string expression for its ‹parsed-body›; newlines and following indentations are converted to "\n" and all-space string expressions.
|
| reads as |
| ||||
| |||||||
|
| reads as |
| ||||
| |||||||
|
| reads as |
|
The command part of an @-form is optional as well. In that case, the @-form is read as a list, which usually counts as a function application, but it also useful when quoted with the usual Racket quote:
| @{blah blah} | reads as | ("blah blah") | ||||||
| |||||||||
| @{blah @[3]} | reads as | ("blah " (3)) | ||||||
| |||||||||
|
| reads as |
|
Finally, we can also drop the datum and text parts, which leaves us with
only the command—
| @foo | reads as | foo |
| @{blah @foo blah} | reads as | ("blah " foo " blah") |
| @{blah @foo: blah} | reads as | ("blah " foo: " blah") |
| @{blah @|foo|: blah} | reads as | ("blah " foo ": blah") |
Actually, the command part can be any Racket expression (that does not start with [, {, or |), which is particularly useful with such escapes since they can be used with any expression.
| @foo{(+ 1 2) -> @(+ 1 2)!} | reads as | (foo "(+ 1 2) -> " (+ 1 2) "!") |
| @foo{A @"string" escape} | reads as | (foo "A string escape") |
| @"@" | reads as | "@" |
Note that an escaped Racket string is merged with the surrounding text as a special case. This is useful if you want to use the special characters in your string, but escaping braces are not necessary if they are balanced.
| @foo{eli@"@"barzilay.org} | reads as | (foo "eli@barzilay.org") | ||||||
| |||||||||
| @foo{A @"{" begins a block} | reads as | (foo "A { begins a block") | ||||||
| |||||||||
|
| reads as |
|
In some cases, a text contains many literal @s, which can be cumbersome to quote individually. For such case, braces have an alternative syntax: A block of text can begin with a “|{” and terminated accordingly with a “}|”. Furthermore, any nested @-forms must begin with a “|@”.
| @foo|{bar}@{baz}| | reads as | (foo "bar}@{baz") |
| @foo|{bar |@x{X} baz}| | reads as | (foo "bar " (x "X") " baz") |
| @foo|{bar |@x|{@}| baz}| | reads as | (foo "bar " (x "@") " baz") |
In cases when even this is not convenient enough, punctuation characters can be added between the | and the braces and the @ in nested forms. (The punctuation is mirrored for parentheses and <>s.) With this extension, @-form syntax can be used as a “here string” replacement.
| @foo|--{bar}@|{baz}--| | reads as | (foo "bar}@|{baz") |
| @foo|<<{bar}@|{baz}>>| | reads as | (foo "bar}@|{baz") |
On the flip side of this is, how can an @ sign be used in Racket code? This is almost never an issue, because Racket strings and characters are still read the same, and @ is set as a non-terminating reader macro so it can be used in Racket identifiers anywhere except in the first character of an identifier. When @ must appear as the first character of an identifier, you must quote the identifier just like other non-standard characters in normal S-expression syntax: with a backslash or with vertical bars.
| (define \@email "foo@bar.com") | reads as | (define @email "foo@bar.com") |
| (define |@atchar| #\@) | reads as | (define @atchar #\@) |
Note that spaces are not allowed before a [ or a {, or they will be part of the following text (or Racket code). (More on using braces in body texts below.)
| @foo{bar @baz[2 3] {4 5}} | reads as | (foo "bar " (baz 2 3) " {4 5}") |
Finally, remember that @-forms are just an alternate form of S-expressions. Identifiers still get their meaning, as in any Racket code, through the lexical context in which they appear. Specifically, when the above @-form appears in a Racket expression context, the lexical environment must provide bindings for foo as a procedure or a macro; it can be defined, required, or bound locally (with let, for example).
> (let* ([formatter (lambda (fmt) (lambda args (format fmt (apply string-append args))))] [bf (formatter "*~a*")] [it (formatter "/~a/")] [ul (formatter "_~a_")] [text string-append]) @text{@it{Note}: @bf{This is @ul{not} a pipe}.}) "/Note/: *This is _not_ a pipe*."
2.2 The Command Part
Besides being a Racket identifier, the ‹cmd› part of an @-form can have Racket punctuation prefixes, which will end up wrapping the whole expression.
| @`',@foo{blah} | reads as | `',@(foo "blah") |
| @#`#'#,@foo{blah} | reads as | #`#'#,@(foo "blah") |
When writing Racket code, this means that @`',@foo{blah} is exactly the same as `@',@foo{blah} and `',@@foo{blah}, but unlike the latter two, the first construct can appear in body texts with the same meaning, whereas the other two would not work (see below).
After the optional punctuation prefix, the ‹cmd› itself is not limited to identifiers; it can be any Racket expression.
| @(lambda (x) x){blah} | reads as | ((lambda (x) x) "blah") |
| @`(unquote foo){blah} | reads as | `(,foo "blah") |
In addition, the command can be omitted altogether, which will omit it from the translation, resulting in an S-expression that usually contains, say, just strings:
|
| reads as |
| ||||
| |||||||
|
| reads as |
|
If the command part begins with a ; (with no newline between the @ and the ;), then the construct is a comment. There are two comment forms, one for arbitrary-text and possibly nested comments, and another one for line comments:
@;{ ‹any›* } @; ‹anything-else-without-newline›*
In the first form, the commented body must still parse correctly; see the description of the body syntax below. In the second form, all text from the @; to the end of the line and all following spaces (or tabs) are part of the comment (similar to % comments in TeX).
|
| reads as | (foo "bar bazblah") |
Tip: if you use an editor in some Scheme mode without support for @-forms, balanced comments can be confusing, since the open brace looks commented out, and the closing one isn’t. In such cases it is useful to “comment” out the closing brace too:
@;{ |
... |
;} |
so the editor does not treat the file as having unbalanced parentheses.
If only the ‹cmd› part of an @-form is specified, then the result is the command part only, without an extra set of parenthesis. This makes it suitable for Racket escapes in body texts. (More on this below, in the description of the body part.)
| @foo{x @y z} | reads as | (foo "x " y " z") |
| @foo{x @(* y 2) z} | reads as | (foo "x " (* y 2) " z") |
| @{@foo bar} | reads as | (foo " bar") |
Finally, note that there are currently no special rules for using @ in the command itself, which can lead to things like:
| @@foo{bar}{baz} | reads as | ((foo "bar") "baz") |
2.3 The Datum Part
The datum part can contain arbitrary Racket expressions, which are simply stacked before the body text arguments:
| @foo[1 (* 2 3)]{bar} | reads as | (foo 1 (* 2 3) "bar") |
| @foo[@bar{...}]{blah} | reads as | (foo (bar "...") "blah") |
The body part can still be omitted, which is essentially an alternative syntax for plain (non-textual) S-expressions:
| @foo[bar] | reads as | (foo bar) |
| @foo{bar @f[x] baz} | reads as | (foo "bar " (f x) " baz") |
The datum part can be empty, which makes no difference, except when the body is omitted. It is more common, however, to use an empty body for the same purpose.
| @foo[]{bar} | reads as | (foo "bar") |
| @foo[] | reads as | (foo) |
| @foo | reads as | foo |
| @foo{} | reads as | (foo) |
The most common use of the datum part is for Racket forms that expect keyword-value arguments that precede the body of text arguments.
| @foo[#:style 'big]{bar} | reads as | (foo #:style 'big "bar") |
2.4 The Body Part
The syntax of the body part is intended to be as convenient as
possible for free text. It can contain almost any text—
| @foo{f{o}o} | reads as | (foo "f{o}o") |
| @foo{{{}}{}} | reads as | (foo "{{}}{}") |
As described above, the text turns to a sequence of string arguments for the resulting form. Spaces at the beginning and end of lines are discarded, and newlines turn to individual "\n" strings (i.e., they are not merged with other body parts); see also the information about newlines and indentation below. Spaces are not discarded if they appear after the open { (before the closing }) when there is also text that follows (precedes) it; specifically, they are preserved in a single-line body.
| @foo{bar} | reads as | (foo "bar") |
| @foo{ bar } | reads as | (foo " bar ") |
| @foo[1]{ bar } | reads as | (foo 1 " bar ") |
If @ appears in a body, then it is interpreted as Racket code, which means that the @-reader is applied recursively, and the resulting syntax appears as part of the S-expression, among other string contents.
| @foo{a @bar{b} c} | reads as | (foo "a " (bar "b") " c") |
If the nested @ construct has only a command—
| @foo{a @bar c} | reads as | (foo "a " bar " c") |
| @foo{a @(bar 2) c} | reads as | (foo "a " (bar 2) " c") |
This is particularly useful with strings, which can be used to include arbitrary text.
| @foo{A @"}" marks the end} | reads as | (foo "A } marks the end") |
Note that the escaped string is (intentionally) merged with the rest of the text. This works for @ too:
| @foo{The prefix: @"@".} | reads as | (foo "The prefix: @.") |
| @foo{@"@x{y}" --> (x "y")} | reads as | (foo "@x{y} --> (x \"y\")") |
2.4.1 Alternative Body Syntax
In addition to the above, there is an alternative syntax for the body, one that specifies a new marker for its end: use |{ for the opening marker to have the text terminated by a }|.
| @foo|{...}| | reads as | (foo "...") |
| @foo|{"}" follows "{"}| | reads as | (foo "\"}\" follows \"{\"") |
| @foo|{Nesting |{is}| ok}| | reads as | (foo "Nesting |{is}| ok") |
This applies to sub-@-forms too—
|
| reads as |
| ||||||
| |||||||||
| @t|{In |@i|{sub|@"@"s}| too}| | reads as | (t "In " (i "sub@s") " too") |
Note that the subform uses its own delimiters, {...} or |{...}|. This means that you can copy and paste Scribble text with @-forms freely, just prefix the @ if the immediate surrounding text has a prefix.
For even better control, you can add characters in the opening delimiter, between the | and the {. Characters that are put there (non alphanumeric ASCII characters only, excluding { and @) should also be used for sub-@-forms, and the end-of-body marker should have these characters in reverse order with paren-like characters ((, [, <) mirrored.
| @foo|<<<{@x{foo} |@{bar}|.}>>>| | reads as | (foo "@x{foo} |@{bar}|.") |
| @foo|!!{X |!!@b{Y}...}!!| | reads as | (foo "X " (b "Y") "...") |
Finally, remember that you can use an expression escape with a Racket string for confusing situations. This works well when you only need to quote short pieces, and the above works well when you have larger multi-line body texts.
2.4.2 Racket Expression Escapes
In some cases, you may want to use a Racket identifier (or a number or a boolean etc.) in a position that touches the following text; in these situations you should surround the escaped Racket expression by a pair of | characters. The text inside the bars is parsed as a Racket expression.
| @foo{foo@bar.} | reads as | (foo "foo" bar.) |
| @foo{foo@|bar|.} | reads as | (foo "foo" bar ".") |
| @foo{foo@3.} | reads as | (foo "foo" 3.0) |
| @foo{foo@|3|.} | reads as | (foo "foo" 3 ".") |
This form is a generic Racket expression escape, there is no body text or datum part when you use this form.
| @foo{foo@|(f 1)|{bar}} | reads as | (foo "foo" (f 1) "{bar}") |
| @foo{foo@|bar|[1]{baz}} | reads as | (foo "foo" bar "[1]{baz}") |
This works for string expressions too, but note that unlike the above, the string is (intentionally) not merged with the rest of the text:
| @foo{x@"y"z} | reads as | (foo "xyz") |
| @foo{x@|"y"|z} | reads as | (foo "x" "y" "z") |
Expression escapes also work with any number of expressions,
| @foo{x@|1 (+ 2 3) 4|y} | reads as | (foo "x" 1 (+ 2 3) 4 "y") | ||||
| |||||||
|
| reads as |
|
It seems that @|| has no purpose—
|
| reads as |
|
Note that @|{...}| can be parsed as either an escape expression or as the Racket command part of an @-form. The latter is used in this case (since there is little point in Racket code that uses braces.
| @|{blah}| | reads as | ("blah") |
2.4.3 Comments
As noted above, there are two kinds of @-form comments: @;{...} is a (nestable) comment for a whole body of text (following the same rules for @-forms), and @;... is a line-comment.
|
| reads as |
|
One useful property of line-comments is that they continue to the end of the line and all following spaces (or tabs). Using this, you can get further control of the subforms.
|
| reads as | (foo "A long single-string arg.") |
Note how this is different from using @||s in that strings around it are not merged.
2.4.4 Spaces, Newlines, and Indentation
The @-form syntax treats spaces and newlines in a special way is meant to be sensible for dealing with text. As mentioned above, spaces at the beginning and end of body lines are discarded, except for spaces between a { and text, or between text and a }.
| @foo{bar} | reads as | (foo "bar") | ||||
| |||||||
| @foo{ bar } | reads as | (foo " bar ") | ||||
| |||||||
|
| reads as |
|
A single newline that follows an open brace or precedes a closing brace is discarded, unless there are only newlines in the body; other newlines are read as a "\n" string
|
| reads as | (foo "bar") | |||||||||
| ||||||||||||
|
| reads as |
| |||||||||
| ||||||||||||
|
| reads as |
| |||||||||
| ||||||||||||
|
| reads as |
| |||||||||
| ||||||||||||
|
| reads as | (foo "\n") | |||||||||
| ||||||||||||
|
| reads as |
| |||||||||
| ||||||||||||
|
| reads as |
|
Spaces at the beginning of body lines do not appear in the resulting S-expressions, but the column of each line is noticed, and all-space indentation strings are added so the result has the same indentation. A indentation string is added to each line according to its distance from the leftmost syntax object (except for empty lines). (Note: if you try these examples on a Racket REPL, you should be aware that the reader does not know about the “> ” prompt.)
|
| reads as |
| |||||||||
| ||||||||||||
|
| reads as |
| |||||||||
| ||||||||||||
|
| reads as |
|
If the first string came from the opening { line, it is not prepended with an indentation (but it can affect the leftmost syntax object used for indentation). This makes sense when formatting structured code as well as text (see the last example in the following block).
|
| reads as |
| ||||||
| |||||||||
|
| reads as |
| ||||||
| |||||||||
|
| reads as |
| ||||||
| |||||||||
|
| reads as |
| ||||||
| |||||||||
|
| reads as |
| ||||||
| |||||||||
|
| reads as |
|
Note that each @-form is parsed to an S-expression that has its own indentation. This means that Scribble source can be indented like code, but if indentation matters then you may need to apply indentation of the outer item to all lines of the inner one. For example, in
@code{ |
begin |
i = 1, r = 1 |
@bold{while i < n do |
r *= i++ |
done} |
end |
} |
a formatter will need to apply the 2-space indentation to the rendering of the bold body.
Note that to get a first-line text to be counted as a leftmost line, line and column accounting should be on for the input port (use-at-readtable turns them on for the current input port). Without this,
@foo{x1 |
x2 |
x3} |
will not have 2-space indentations in the parsed S-expression if source accounting is not on, but
@foo{x1 |
x2 |
x3} |
will (due to the last line). Pay attention to this, as it can be a problem with Racket code, for example:
@code{(define (foo x) |
(+ x 1))} |
For rare situations where spaces at the beginning (or end) of lines matter, you can begin (or end) a line with a @||.
|
| reads as |
|
3 High-Level Scribble API
3.1 Base Document Format
| #lang scribble/base | package: scribble-lib |
Functions provided by this library, such as title and italic, might be called from Racket as
(title #:tag "how-to" "How to Design " (italic "Great") " Programs")
They can also be called with @ notation as
@title[#:tag "how-to"]{How to Design @italic{Great} Programs} |
Although the procedures are mostly designed to be used from @ mode, they are easier to document in Racket mode (partly because we have scribble/manual).
3.1.1 Document Structure
procedure
(title [ #:tag tag #:tag-prefix tag-prefix #:style style #:version vers #:date date] pre-content ...+) → title-decl? tag : (or/c #f string? (listof string?)) = #f tag-prefix : (or/c #f string? module-path?) = #f style : (or/c style? #f string? symbol? (listof symbol?)) = #f vers : (or/c string? #f) = #f date : (or/c string? #f) = #f pre-content : pre-content?
The style argument can be a style structure, or it can be one of the following: a #f that corresponds to a “plain” style, a string that is used as a style name, a symbol that is used as a style property, or a list of symbols to be used as style properties. For information on styles, see part. For example, a style of 'toc causes sub-sections to be generated as separate pages in multi-page HTML output.
The tag-prefix argument is propagated to the generated structure (see Tags). If tag-prefix is a module path, it is converted to a string using module-path-prefix->string.
The vers argument is propagated to the title-decl structure. Use "" as vers to suppress version rendering in the output.
The date argument is propagated to the title-decl structure via a document-date style property. Use "" as date to suppress date rendering in Latex output.
The section title is automatically indexed by decode-part. For the index key, leading whitespace and a leading “A”, “An”, or “The” (followed by more whitespace) is removed.
procedure
(section [ #:tag tag #:tag-prefix tag-prefix #:style style] pre-content ...+) → part-start? tag : (or/c #f string? (listof string?)) = #f tag-prefix : (or/c #f string? module-path?) = #f style : (or/c style? #f string? symbol? (listof symbol?)) = #f pre-content : pre-content?
procedure
(subsection [ #:tag tag #:tag-prefix tag-prefix #:style style] pre-content ...+) → part-start? tag : (or/c #f string? (listof string?)) = #f tag-prefix : (or/c #f string? module-path?) = #f style : (or/c style? #f string? symbol? (listof symbol?)) = #f pre-content : pre-content?
procedure
(subsubsection [ #:tag tag #:tag-prefix tag-prefix #:style style] pre-content ...+) → part-start? tag : (or/c #f string? (listof string?)) = #f tag-prefix : (or/c #f string? module-path?) = #f style : (or/c style? #f string? symbol? (listof symbol?)) = #f pre-content : pre-content?
procedure
(subsubsub*section [ #:tag tag #:tag-prefix tag-prefix #:style style] pre-content ...+) → paragraph? tag : (or/c #f string? (listof string?)) = #f tag-prefix : (or/c #f string? module-path?) = #f style : (or/c style? #f string? symbol? (listof symbol?)) = #f pre-content : pre-content?
syntax
(include-section module-path)
Examples:
@author{Alice P. Racketeer}
procedure
(author+email author-name [ #:obfuscate? obfuscate?]) → element? author-name : content? email : string? obfuscate? : any/c = #f
Note that author+email is not a replacement for author. The author+email function is often used in combination with author.
Examples:
@author[(author+email "Bob T. Scribbler" "bob@racket-lang.org")]
3.1.2 Blocks
procedure
(para [#:style style] pre-content ...) → paragraph?
style : (or/c style? string? symbol? #f) = #f pre-content : pre-content?
The style argument can be a style, #f to indicate a “plain” style, a string that is used as a style name, or a symbol that is used as a style name. (Note that section and para treat symbols differently as style arguments.)
procedure
(nested [#:style style] pre-flow ...) → nested-flow?
style : (or/c style? string? symbol? #f) = #f pre-flow : pre-flow?
The style argument is handled the same as para. The 'inset and 'code-inset styles cause the nested flow to be inset compared to surrounding text, with the latter particularly intended for insetting code. The default style is specified by the output destination (and tends to inset text for HTML output and not inset for Latex output).
procedure
(centered pre-flow ...) → nested-flow?
pre-flow : pre-flow?
procedure
(margin-note pre-flow ... [#:left? left?]) → block?
pre-flow : pre-flow? left? : any/c = #f
If left? is true, then the note is shown on the opposite as it would normally be shown (which is the left-hand side for HTML output). Beware of colliding with output for a table of contents.
procedure
(margin-note* pre-content ... [#:left? left?]) → element?
pre-content : pre-content? left? : any/c = #f
procedure
(itemlist itm ... [#:style style]) → itemization?
itm : items/c style : (or/c style? string? symbol? #f) = #f
The style argument is handled the same as para. The 'ordered style numbers items, instead of just using a bullet.
value
procedure
(tabular cells [ #:style style #:sep sep #:column-properties column-properties #:row-properties row-properties #:cell-properties cell-properties #:sep-properties sep-properties]) → table? cells : (listof (listof (or/c block? content? 'cont))) style : (or/c style? string? symbol? #f) = #f sep : (or/c block? content? #f) = #f column-properties : (listof any/c) = '() row-properties : (listof any/c) = '() cell-properties : (listof (listof any/c)) = '() sep-properties : (or/c list? #f) = #f
Use 'cont in cells as a cell to continue the content of the preceding cell in a row in the space that would otherwise be used for a new cell. A 'cont must not appear as the first cell in a row.
The style argument is handled the same as para. See table for a list of recognized style names and style properties.
The default style places no space between table columns. If sep is not #f, it is inserted as a new column between every column in the table; the new column’s properties are the same as the preceding column’s, unless sep-properties provides a list of style properties to use. When sep would be placed before a 'cont, a 'cont is inserted, instead.
The column-properties, row-properties, and cell-properties arguments specify style properties for the columns and cells of a table; see table-columns and table-cells for a description of recognized properties. The lists do not contain entries for columns potentially introduced for sep, and when non-empty, they are extended as needed to match the table size determined by cells:
If the length of column-properties is less than the length of each row in cells, the last item of the list is duplicated to make the list long enough.
If the length of row-properties is less than the length of cells, the last item of the list is duplicated to make the list long enough.
If the length of cell-properties is less than the number of rows in cells, then the last element is duplicated to make the list long enough. Each list within cell-properties is treated like a column-properties list—
expanded as needed to match the number of columns in each row.
Each element of column-properties or row-properties is either a list of style property values or a non-list element that is wrapped as a list. Similarly, for each list that is an element of cell-properties, the list’s non-list elements are wrapped as nested lists.
If column-properties is non-empty, then its list of property
lists is converted into a table-columns style property
that is added to the style specified by style—
If the style lists for column-properties are both merged with cell-properties and converted to table-columns, then style will contain some redundant information. In that case, column-attributes properties will be used from table-columns, while other properties will be used from the merger into table-cells.
Changed in version 1.1 of package scribble-lib: Added the #:column-properties,
#:row-properties,
and #:cell-properties arguments.
Changed in version 1.12: Changed sep insertion before a
'cont.
Changed in version 1.28: Added sep-properties and made
the preceding column’s properties used
consistently if not specified.
@tabular[#:sep @hspace[1] (list (list "soup" "gazpacho") (list "soup" "tonjiru"))] @tabular[#:style 'boxed #:column-properties '(left right) #:row-properties '(bottom-border ()) (list (list @bold{recipe} @bold{vegetable}) (list "caldo verde" "kale") (list "kinpira gobō" "burdock") (list "makizushi" 'cont))]
Renders like:
soup
gazpacho
soup
tonjiru
recipe
vegetable
caldo verde
kale
kinpira gobō
burdock
makizushi
procedure
indent : exact-nonnegative-integer? = 0 elem : content?
The string elems are not decoded with decode-content, so (verbatim "---") renders with three hyphens instead of an em dash. Beware, however, that reading @verbatim converts @ syntax within the argument, and such reading occurs well before arguments to verbatim are delivered at run-time. To disable simple @ notation within the verbatim argument, verbatim is typically used with |{...}| or similar brackets, like this:
@verbatim|{ |
Use @bold{---} like this... |
}| |
which renders as
Use @bold{---} like this... |
while
@verbatim|{ |
Use |@bold{---} like this... |
}| |
renders as
Use — |
Even with brackets like |{...}|, beware that consistent leading whitespace is removed by the parser; see Alternative Body Syntax for more information.
See also literal.
3.1.3 Text Styles and Content
procedure
pre-content : pre-content? style : (or/c style? string? symbol? #f) = #f
procedure
pre-content : pre-content?
procedure
pre-content : pre-content?
procedure
pre-content : pre-content?
To apply the 'tt style uniformly to all pre-content arguments, use (elem #:style 'tt pre-content ...), instead.
procedure
pre-content : pre-content?
procedure
(superscript pre-content ...) → element?
pre-content : pre-content?
procedure
pre-content : pre-content?
procedure
pre-content : pre-content?
procedure
pre-content : pre-content?
Beware that @ for a literal call performs some processing before delivering arguments to literal. The literal form can be used with |{...}| or similar brackets to disable @ notation within the literal argument, like this:
@literal|{@bold{---}}| |
which renders as
@bold{---} |
See also verbatim.
3.1.4 Images
procedure
(image path [ #:scale scale #:suffixes suffixes #:style style] pre-content ...) → image-element? path : (or/c path-string? (cons/c 'collects (listof bytes?))) scale : real? = 1.0 suffixes : (listof #rx"^[.]") = null style : (or/c style? string? symbol? #f) = #f pre-content : pre-content?
If path is a relative path, it is relative to the current directory, which is set by raco setup to the directory of the main document file. (In general, however, it’s more reliable to express relative paths using define-runtime-path.) Instead of a path or string, the path argument can be a result of path->main-collects-relative.
The scale argument sets the images scale relative to its default size as determined by the content of path. For HTML output, the resulting image-element is rendered with an img or object (for SVG) tag, and scale adjusts the width and height attributes; a class name or other attributes in style can effectively override that size.
The strings in suffixes are filtered to those supported by given renderer, and then the acceptable suffixes are tried in order. The HTML renderer supports ".png", ".gif", and ".svg", while the Latex renderer supports ".png", ".pdf", and ".ps" (but ".ps" works only when converting Latex output to DVI, and ".png" and ".pdf" work only for converting Latex output to PDF).
Note that when the suffixes list is non-empty, then the path argument should not have a suffix.
Changed in version 1.3 of package scribble-lib: Added the #:style argument.
3.1.5 Spacing
procedure
(nonbreaking pre-content ...) → element?
pre-content : pre-content?
procedure
n : exact-nonnegative-integer?
See .__ for an example.
The following example illustrates both ._ and .__:
#lang scribble/base My name is Mr@._ T@.__ I pity the fool who can't typeset punctuation.
3.1.6 Links
procedure
(hyperlink url pre-content ... [ #:underline? underline? #:style style]) → element? url : string? pre-content : pre-content? underline? : any/c = #t
style : (or/c style? string? symbol? #f) = (if underline? #f "plainlink")
procedure
(secref tag [ #:doc module-path #:tag-prefixes prefixes #:underline? underline? #:link-render-style ref-style]) → element? tag : string? module-path : (or/c module-path? #f) = #f prefixes : (or/c (listof string?) #f) = #f underline? : any/c = #t ref-style : (or/c link-render-style? #f) = #f
If #:doc module-path is provided, the tag refers to a tag with a prefix determined by module-path. When raco setup renders documentation, it automatically adds a tag prefix to the document based on the source module. Thus, for example, to refer to a section of the Racket reference, module-path would be '(lib "scribblings/reference/reference.scrbl").
The #:tag-prefixes prefixes argument similarly supports selecting a particular section as determined by a path of tag prefixes. When a #:doc argument is provided, then prefixes should trace a path of tag-prefixed subsections to reach the tag section. When #:doc is not provided, the prefixes path is relative to any enclosing section (i.e., the youngest ancestor that produces a match).
For the result link-element, if ref-style is not #f, then it is attached as a style property and affects the rendering of the link. Alternatively, an enclosing part can have a link-render style that adjusts the rendering style for all links within the part. See link-element for more information about the rendering of section references.
If underline? is #f, then a style is attached to the result link-element so that the hyperlink is rendered in HTML without an underline
In Racket documentation that is rendered to HTML, clicking on a section title normally shows the secref call that is needed to link to the section.
Changed in version 1.25 of package scribble-lib: Added the #:link-render-style argument.
procedure
(Secref tag [ #:doc module-path #:tag-prefixes prefixes #:underline? underline? #:link-render-style ref-style]) → element? tag : string? module-path : (or/c module-path? #f) = #f prefixes : (or/c (listof string?) #f) = #f underline? : any/c = #t ref-style : (or/c link-render-style? #f) = #f
Changed in version 1.25 of package scribble-lib: Added the #:link-render-style argument.
procedure
(seclink tag [ #:doc module-path #:tag-prefixes prefixes #:underline? underline? #:indirect? indirect?] pre-content ...) → element? tag : string? module-path : (or/c module-path? #f) = #f prefixes : (or/c (listof string?) #f) = #f underline? : any/c = #t indirect? : any/c = #f pre-content : pre-content?
In addition to secref’s arguments, seclink supports a indirect? argument. When indirect? is true, then the section hyperlink’s resolution in HTML is potentially delayed; see 'indirect-link for link-element.
procedure
(other-doc module-path [ #:underline? underline? #:indirect indirect]) → element? module-path : module-path? underline? : any/c = #t indirect : (or/c #f content?) = #f
If indirect is not #f, then the link’s resolution in HTML can be delayed, like seclink with #:indirect? #t. The indirect content is prefixed with “the” and suffixed with “documentation” to generate the rendered text of the link. For example:
@other-doc['(lib "parsack/parsack/parsack.scrbl") |
#:indirect "Parsec implementation in Racket"] |
renders as a hyperlink with the text:
the Parsec implementation in Racket documentation |
procedure
t : (or/c taglet? generated-tag?) pre-content : pre-content?
procedure
(elemref t pre-content ... [ #:underline? underline?]) → element? t : (or/c taglet? generated-tag?) pre-content : pre-content? underline? : any/c = #t
3.1.7 Indexing
procedure
(index words pre-content ...) → index-element?
words : (or/c string? (listof string?)) pre-content : pre-content?
Use index when an index entry should point to a specific word or phrase within the typeset document (i.e., the pre-content). Use section-index, instead, to create an index entry that leads to a section, instead of a specific word or phrase within the section.
procedure
(index* words word-contents pre-content ...) → index-element?
words : (listof string?) word-contents : (listof list?) pre-content : pre-content?
procedure
(as-index pre-content ...) → index-element?
pre-content : pre-content?
procedure
(section-index word ...) → part-index-decl?
word : string?
procedure
(index-section [#:tag tag]) → part?
tag : (or/c #f string?) = "doc-index"
3.1.8 Tables of Contents
procedure
procedure
(local-table-of-contents [#:style style]) → delayed-block?
style : (or/c symbol? #f) = #f
The meaning of the style argument depends on the output type, but 'immediate-only normally creates a table of contents that contains only immediate sub-sections of the enclosing section. See also the 'quiet style of part (i.e., in a part structure, not supplied as the style argument to local-table-of-contents), which normally suppresses sub-part entries in a table of contents.
3.1.9 Tags
The exports of scribble/tag are all re-exported by scribble/base.
3.2 Racket Manual Format
The scribble/manual language is a major component of Scribble, and it is documented in its own chapter: Scribbling Documentation.
3.3 Book Format
| #lang scribble/book | package: scribble-lib |
3.4 Report Format
| #lang scribble/report | package: scribble-lib |
3.5 SIGPLAN Paper Format
| #lang scribble/sigplan | package: scribble-lib |
syntax
#lang scribble/sigplan @preprint |
syntax
#lang scribble/sigplan @10pt |
syntax
#lang scribble/sigplan @nocopyright |
syntax
#lang scribble/sigplan @onecolumn
syntax
#lang scribble/sigplan @notimes
syntax
#lang scribble/sigplan @noqcourier
The 10pt, preprint, nocopyright, onecolumn, notimes, and noqcourier options can be used together and may appear in any order.
procedure
pre-content : pre-content?
syntax
(include-abstract module-path)
procedure
pre-content : pre-content?
procedure
(authorinfo name affiliation email) → block?
name : pre-content? affiliation : pre-content? email : pre-content?
procedure
(conferenceinfo conference location) → block?
conference : pre-content? location : pre-content?
procedure
(copyrightyear content ...) → block?
content : pre-content?
procedure
(copyrightdata content ...) → block?
content : pre-content?
procedure
content : pre-content?
procedure
procedure
content : pre-content?
Added in version 1.13 of package scribble-lib.
procedure
(category CR-number subcategory third-level [ fourth-level]) → content? CR-number : pre-content? subcategory : pre-content? third-level : pre-content? fourth-level : (or/c #f pre-content?) = #f
procedure
content : pre-content?
procedure
content : pre-content?
For category, the subcategory argument should be in titlecase (i.e., capitalize the first letter of each word) and a phrase at the level of “Programming Languages” or “Software Engineering” (as opposed to a category like “Software” or a third-level name like “Concurrent Programming” or “Processors”). A third-level phrase should be in titlecase. A fourth-level phrase, if any, should not be capitalized.
For terms, each general term should be in titlecase. Terms are usually drawn from a fixed list, and they are usually optional.
For keywords, capitalize only the first letter of the first word, separate phrases by commas, and do not include “and” before the last one. Keywords should be noun phrases, not adjectives.
3.6 ACM Paper Format
| #lang scribble/acmart | package: scribble-lib |
Note: a scribble/acmart document must include a title and author.
Example:
#lang scribble/acmart |
@title{Surreal Numbers} |
@author{Ursula N. Owens} |
syntax
syntax
syntax
syntax
syntax
syntax
syntax
syntax
syntax
syntax
syntax
syntax
#lang scribble/acmart @acmsmall |
The manuscript, acmsmall, acmlarge, acmtog, sigconf, siggraph, sigplan, sigchi, and sigchi-a formats are all mutually exclusive.
syntax
syntax
syntax
syntax
syntax
syntax
syntax
syntax
syntax
syntax
syntax
syntax
syntax
#lang scribble/acmart @acmsmall @review @anonymous @natbib |
If multiple font size options are used, all but the last are ignored.
The ACM documentation (version 1.54, 2018-07-16, by Boris Veytsman) provides these defaults and descriptions:
name |
| default |
| description |
review |
| false |
| A review version: lines are numbered and hyperlinks are colored |
screen |
| see text |
| A screen version: hyperlinks are colored |
natbib |
| true |
| Whether to use the natbib package |
anonymous |
| false |
| Whether to make author(s) anonymous |
authorversion |
| false |
| Whether to generate a special version for the authors’ personal use or posting |
nonacm |
| false |
| Use the class typesetting options for a non-ACM document, which will not include the conference/journal header and footers or permission statements |
timestamp |
| false |
| Whether to put a time stamp in the footer of each page |
authordraft |
| false |
| Whether author’s-draft mode is enabled |
acmthm |
| true |
| Whether to define theorem-like environments |
Further details for some of these are provided by the full documentation for the acmart LaTeX class.
In order to disable a default-true option (e.g. natbib), call the option as a function with the value #false:
#lang scribble/acmart @natbib[#f] @sigplan
procedure
pre-content : pre-content?
syntax
(include-abstract module-path)
procedure
(title [ #:short short-title #:tag tag #:tag-prefix prefix #:style style #:version version #:date date] title ...) → title-decl? short-title : pre-content? = #f tag : (or/c string? (listof string?) #f) = #f prefix : (or/c string? module-path? #f) = #f style : (or/c style? string? symbol? #f) = #f version : (or/c string? #f) = #f date : (or/c string? #f) = #f title : pre-content?
procedure
pre-content : pre-content?
procedure
(author [ #:orcid orcid #:affiliation affiliation #:email email] name ...) → block? orcid : (or/c pre-content? #f) = #f
affiliation :
(or/c pre-content? affiliation? (listof pre-content?) (listof affiliation?) #f) = #f email : (or/c pre-content? email? (listof email?)) = '() name : pre-content?
#lang scribble/acmart @title{Title} @author["Unboxed Value" #:email (list (email "user@server.com") (email-string "case--Int#@GHC.Prim.info"))]} @abstract{abstracting abstract title}
procedure
(acmJournal journal ...) → block?
journal : pre-content?
procedure
(acmConference name date venue) → block?
name : pre-content? date : pre-content? venue : pre-content?
procedure
content : pre-content?
procedure
content : pre-content?
procedure
(acmArticle content ...) → block?
content : pre-content?
procedure
content : pre-content?
procedure
content : pre-content?
procedure
(acmArticleSeq content ...) → block?
content : pre-content?
procedure
content : pre-content?
procedure
content : pre-content?
procedure
content : pre-content?
procedure
text : pre-content?
procedure
(email-string text ...) → email?
text : string?
email-string is like email except that email-string only takes strings, escapes all % and # characters in the arguments and typesets the email address with the 'exact-chars style.
procedure
(affiliation [ #:position position #:institution institution #:street-address street-address #:city city #:state state #:postcode postcode #:country country]) → affiliation? position : (or/c pre-content? #f) = #f institution : (listof (or/c pre-content? institution?)) = '() street-address : (or/c pre-content? #f) = #f city : (or/c pre-content? #f) = #f state : (or/c pre-content? #f) = #f postcode : (or/c pre-content? #f) = #f country : (or/c pre-content? #f) = #f
procedure
(affiliation? aff) → boolean?
aff : any/c
procedure
(institution [ #:departments departments] inst ...) → institution?
departments : (or/c pre-content? institution? (listof institution)) = '() inst : institution?
procedure
(institution? inst) → boolean
inst : any/c
#lang scribble/acmart @title{Some Title} @author["David Van Horn" #:affiliation @affiliation[ #:institution @institution[ #:departments (list @institution{Department of Computer Science} @institution{UMIACS})]{ University of Maryland} #:city "College Park" #:state "Maryland"] #:email "dvanhorn@cs.umd.edu"]} @abstract{This is an abstract.}
procedure
(authorsaddresses addresses ...) → block?
addresses : pre-content?
The addresses parameter takes the address text. As a special case the empty list removes the addresses field entirely.
#lang scribble/acmart @acmsmall @title{A fancy paper} @author["Ronon Dex"] @authorsaddresses{}
Added in version 1.26 of package scribble-lib.
procedure
(shortauthors name ...) → element?
name : pre-content?
Added in version 1.29 of package scribble-lib.
procedure
content : pre-content?
procedure
content : pre-content?
For terms, each general term should be in titlecase. Terms are usually drawn from a fixed list, and they are usually optional.
For keywords, capitalize only the first letter of the first word, separate phrases by commas, and do not include “and” before the last one. Keywords should be noun phrases, not adjectives.
procedure
content : pre-content?
procedure
number? : #f content : pre-content?
@received{February 2007} @received[#:stage "revised"]{March 2009} @received[#:stage "accepted"]{June 2009}
procedure
(teaserfigure content ...) → block?
content : pre-flow?
procedure
content : pre-flow?
procedure
(marginfigure content ...) → block?
content : pre-flow?
procedure
(margintable content ...) → block?
content : pre-flow?
procedure
content : pre-flow?
procedure
(screenonly content ...) → block?
content : pre-flow?
procedure
(anonsuppress content ...) → block?
content : pre-flow?
procedure
(grantsponsor sponsorID name url) → content?
sponsorID : string? name : string? url : string?
procedure
url : string? = #f sponsorID : string? num : string?
Here sponsorID is the unique ID used to match grants to sponsors, name is the name of the sponsor. The sponsorID of a grantnum must match some sponsorID of a grantsponsor command.
@acks{ The author thanks Ben Greenman for helpful comments on this code. Financial support provided by the @grantsponsor["NSF7000" "National Scribble Foundation"]{http://racket-lang.org} under grant No.: @grantnum["NSF7000"]{867-5309}.}
Added in version 1.20 of package scribble-lib.
3.7 JFP Paper Format
| #lang scribble/jfp | package: scribble-lib |
Latex output with scribble/jfp uses a main-document version supplied to title as the short-form document name (to be used in page headers).
procedure
pre-content : pre-content?
syntax
(include-abstract module-path)
procedure
name : pre-content?
procedure
((author/short short-name ...) long-name ...) → block?
short-name : pre-content? long-name : pre-content?
procedure
(affiliation place ...) → element?
place : pre-content?
procedure
(affiliation-mark mark ...) → element?
mark : pre-content?
procedure
#lang scribble/jfp @title{My First Love Story} @((author/short "Romeo M. and Juliet C.") "ROMEO" (affiliation-mark "1") " and " "JULIET" (affiliation-mark "2") @affiliation[ "House Montague" (affiliation-mark "1") (affiliation-sep) "House Capulet" (affiliation-mark "2")])
3.8 LNCS Paper Format
| #lang scribble/lncs | package: scribble-lib |
procedure
pre-content : pre-content?
syntax
(include-abstract module-path)
syntax
(authors auth ...)
auth = (author pre-content-expr ...) | (author #:inst str-expr pre-content-expr ...)
pre-content-expr : pre-content?
str-expr : string?
The #:inst should be a number that matches up to one of the arguments to institutes.
syntax
syntax
(institutes (institute pre-content-expr ...) ...)
pre-content-expr : pre-content?
syntax
syntax
(email pre-content-expr ...)
3.8.1 Example
Here is an example of a paper written in the LNCS format:
For more randomly generated papers, see SCIgen: http://pdos.csail.mit.edu/scigen
#lang scribble/lncs @authors[@author[#:inst "1"]{Lauritz Darragh} @author[#:inst "2"]{Nikolaj Kyran} @author[#:inst "2"]{Kirsten Gormlaith} @author[#:inst "2"]{Tamaz Adrian}] @institutes[ @institute["University of Southeast Boston" @linebreak[] @email|{darragh@cs.seboston.edu}|] @institute["University of Albion" @linebreak[] @email|{{nkyran,gorm,tamaz}@cs.albion.ac.uk}|]] @title{Arak: Low-Energy, Interposable Theory} @abstract{The implications of client-server symmetries have been far-reaching and pervasive. Given the current status of constant-time theory, mathematicians daringly desire the synthesis of rasterization, which embodies the essential principles of algorithms. In this work, we describe a client-server tool for investigating flip-flop gates (Arak), verifying that the producer-consumer problem can be made homogeneous, secure, and wireless.}
4 Scribbling Documentation
The scribble/manual language and associated libraries
provide extensive support for documenting Racket libraries. The
most significant aspect of support for documentation is the way that
source-code bindings are connected to documentation sites through the
module namespace—
4.2.3 Documenting Forms, Functions, Structure Types, and Values |
4.1 Getting Started with Documentation
Although the scribble command-line utility generates output from a Scribble document, documentation of Racket libraries is normally built by raco setup. This chapter emphasizes the raco setup approach, which more automatically supports links across documents.
See Getting Started for information on using the scribble command-line utility.
4.1.1 Setting Up Library Documentation
To document a collection, including a collection implemented by a package:
Create a file in your collection with the file extension ".scrbl". Beware that the file name you choose will determine the output directory’s name, and the directory name must be unique across all installed documents. The remainder of these instructions assume that the file is called "manual.scrbl" (but pick a more specific name in practice).
- Start "manual.scrbl" like this:
#lang scribble/manual @title{My Library} Welcome to my documentation: @racket[(list 'testing 1 2 3)]. The first line starts the file in “text” mode and selects the Racket manual output format. It also introduces bindings like title and racket for writing Racket documentation.
Add the following entry to your collection’s "info.rkt":
(define scribblings '(("manual.scrbl" ())))
The () above is a list of options. When your document gets large enough that you want it split into multiple pages, add the 'multi-page option (omitting the quote, since the whole right-hand side of the definition is already quoted).
If you do not already have an "info.rkt" module, here’s a suitable complete module:
#lang info (define scribblings '(("manual.scrbl" ()))) Run raco setup to build your documentation. For a collection, optionally supply -l followed by the collection name to limit the build process to that collection.
For a collection that is installed as user-specific (e.g., the user package scope), the generated documentation is "doc/manual/index.html" within the collection directory. If the collection is installation-wide, however, then the documentation is generated as "manual/index.html" in the installation’s "doc" directory.
4.1.2 Racket Typesetting and Hyperlinks
In the document source at the start of this chapter (Setting Up Library Documentation), the Racket expression (list 'testing 1 2 3) is typeset properly, but the list identifier is not hyperlinked to the usual definition. To cause list to be hyperlinked, add a require form like this:
@(require (for-label racket))
This require with for-label declaration introduces a document-time binding for each export of the racket module. When the document is built, the racket form detects the binding for list, and so it generates a reference to the specification of list. The setup process detects the reference, and it finds the matching specification in the existing documentation, and ultimately directs the hyperlink to that specification.
Hyperlinks based on for-label and racket are the preferred mechanism for linking to information outside of a single document. Such links require no information about where and how a binding is documented elsewhere:
#lang scribble/manual @(require (for-label racket)) @title{My Library} See also @racket[list].
The racket form typesets a Racket expression for inline text, so it ignores the source formatting of the expression. The racketblock form, in contrast, typesets inset Racket code, and it preserves the expression’s formatting from the document source.
#lang scribble/manual @(require (for-label racket)) @title{My Library} Some example Racket code: @racketblock[ (define (nobody-understands-me what) (list "When I think of all the" what "I've tried so hard to explain!")) (nobody-understands-me "glorble snop") ]
4.1.3 Section Hyperlinks
A section declaration in a document can include a #:tag argument that declares a hyperlink-target tag. The secref function generates a hyperlink, using the section name as the text of the hyperlink. Use seclink to create a hyperlink with text other than the section title.
The following example illustrates section hyperlinks:
#lang scribble/manual @(require (for-label racket)) @title{My Library} Welcome to my documentation: @racket[(list 'testing 1 2 3)]. @table-of-contents[] @section[#:tag "chickens"]{Philadelphia Chickens} Dancing tonight! @section{Reprise} See @secref{chickens}.
Since the page is so short, the hyperlinks in the above example are more effective if you change the "info.rkt" file to add the 'multi-page flag:
(define scribblings '(("manual.scrbl" (multi-page))))
A section can have a tag prefix that applies to all tags as seen from outside the section. Such a prefix is automatically given to each top-level document as processed by raco setup. Thus, referencing a section tag in a different document requires using a prefix, which is based on the target document’s main source file. The following example links to a section in the Racket reference manual:
#lang scribble/manual @(require (for-label racket)) @(define ref-src '(lib "scribblings/reference/reference.scrbl")) @title{My Library} See also @italic{@secref[#:doc ref-src]{pairs}}.
As mentioned in Racket Typesetting and Hyperlinks, however, cross-document references based on (require (for-label ....)) and racket are usually better than cross-document references using secref.
4.1.4 Defining Racket Bindings
Use defproc to document a procedure, defform to document a syntactic form, defstruct to document a structure type, etc. These forms provide consistent formatting of definitions, and they declare hyperlink targets for racket-based hyperlinks.
To document a my-helper procedure that is exported by "helper.rkt" in the "my-lib" collection that contains "manual.scrbl":
Use (require (for-label "helper.rkt")) to import the binding information about the bindings of "helper.rkt" for use when typesetting identifiers. A relative reference "helper.rkt" works since it is relative to the documentation source.
Add a @defmodule[my-lib/helper] declaration, which specifies the library that is being documented within the section. The defmodule form needs an absolute module name mylib/helper, instead of a relative reference "helper.rkt", since the module path given to defmodule appears verbatim in the generated documentation.
Use defproc to document the procedure.
Adding these pieces to "manual.scrbl" gives us the following:
#lang scribble/manual @(require (for-label racket "helper.rkt")) @title{My Library} @defmodule[my-lib/helper] @defproc[(my-helper [lst list?]) (listof (not/c (one-of/c 'cow)))]{ Replaces each @racket['cow] in @racket[lst] with @racket['aardvark].}
In defproc, a contract is specified with each argument to the procedure. In this example, the contract for the lst argument is list?, which is the contract for a list. After the closing parenthesis that ends the argument sequence, the contract of the result must be given; in this case, my-helper guarantees a result that is a list where none of the elements are 'cow.
Some things to notice in this example and the documentation that it generates:
The list?, listof, etc. elements of contracts are hyperlinked to their documentation.
The result contract is formatted in the generated documentation in the same way as in the source. That is, the source layout of contracts is preserved. (In this case, putting the contract all on one line would be better.)
In the prose that documents my-helper, lst is automatically typeset in italic, matching the typesetting in the blue box. The racket form essentially knows that it’s used in the scope of a procedure with argument lst.
If you hover the mouse pointer over my-helper, a popup reports that it is provided from my-lib/helper.
If you use my-helper in any documentation now, as long as that documentation source also has a (require (for-label ....)) of "helper.rkt", then the reference is hyperlinked to the definition above.
See defproc*, defform, etc. for more information on forms to document Racket bindings.
4.1.5 Showing Racket Examples
The examples form from scribble/eval helps you generate examples in your documentation. To use examples, the procedures to document must be suitable for use at documentation time, but the examples form does not use any binding introduced into the document source by require. Instead, create a new evaluator with its own namespace using make-base-eval, and use interaction-eval to require "helper.rkt" in that evaluator. Finally, supply the same evaluator to examples:
#lang scribble/manual @(require scribble/eval (for-label racket "helper.rkt")) @title{My Library} @defmodule[my-lib/helper] @defproc[(my-helper [lst list?]) (listof (not/c (one-of/c 'cow)))]{ Replaces each @racket['cow] in @racket[lst] with @racket['aardvark]. @(define helper-eval (make-base-eval)) @interaction-eval[#:eval helper-eval (require "helper.rkt")] @examples[ #:eval helper-eval (my-helper '()) (my-helper '(cows such remarkable cows)) ]}
4.1.6 Multi-Page Sections
Setting the 'multi-page option (see Section Hyperlinks) causes each top-level section of a document to be rendered as a separate HTML page.
To push sub-sections onto separate pages, use the 'toc style for the enclosing section (as started by title, section, subsection, etc.) and use local-table-of-contents to generate hyperlinks to the sub-sections.
Revising "cows.scrbl" from the previous section:
#lang scribble/manual @title[#:style '(toc)]{Cows} @local-table-of-contents[] @section[#:tag "singing"]{Singing} Wherever they go, it's a quite a show. @section{Dancing} See @secref["singing"].
To run this example, remember to change "info.rkt" to add the 'multi-page style. You may also want to add a call to table-of-contents in "manual.scrbl".
The difference between table-of-contents and local-table-of-contents is that the latter is ignored for Latex output.
When using local-table-of-contents, it often makes sense to include introductory text before the call of local-table-of-contents. When the introductory text is less important and when local table of contents is short, putting the introductory text after the call of local-table-of-contents may be appropriate.
4.2 Manual Forms
| #lang scribble/manual | package: scribble-lib |
4.2.3 Documenting Forms, Functions, Structure Types, and Values |
4.2.1 Typesetting Code
The codeblock and code forms (see #lang-Specified Code) typeset code verbatim, adding a layer of color to the code based on the same syntax-coloring parsers that are used by DrRacket. Input that is parsed as an identifier is further given a lexical context and hyperlinked via for-label imports.
The racketblock and racket forms (see Racket Code) typeset S-expression code roughly verbatim, but roughly by quoting the source term with syntax. Identifiers in the quoted S-expression are hyperlinked via for-label imports.
The two different approaches to typesetting code—
The codeblock and code forms work with non-S-expression syntax, and they give authors more control over output (e.g., the literal number 2/4 is not normalized to 1/2). The codeblock and code forms do not yet support escapes to Scribble element mode, and they cannot adapt spacing based on the width of elements in escapes.
The racketblock and racket forms are more efficient and allow escapes to Scribble element mode. The racketblock and racket forms are tied to S-expression syntax, however, and they are based on a syntax representation that tends to normalize source terms (e.g., the literal number 2/4 is normalized to 1/2).
4.2.1.1 #lang-Specified Code
syntax
(codeblock option ... str-expr ...+)
option = #:keep-lang-line? keep-expr | #:indent indent-expr | #:expand expand-expr | #:context context-expr | #:line-numbers line-number-expr | #:line-number-sep line-number-sep-expr
keep-expr : any/c
indent-expr : exact-nonnegative-integer?
expand-expr : (or/c #f (syntax? . -> . syntax?))
context-expr : (or/c #f syntax?)
line-number-expr : (or/c #f exact-nonnegative-integer?)
line-number-sep-expr : exact-nonnegative-integer?
The str-exprs should normally start with #lang to
determine the reader syntax for the module, but the resulting
“module” need not expand or compile—
When keep-expr produces a true value (the default), the first line in the input (which is typically #lang) is preserved in the typeset output, otherwise the first line is dropped. The typeset code is indented by the amount specified by indent-expr, which defaults to 0.
When expand-expr produces #f (which is the default), identifiers in the typeset code are colored and linked based on for-label bindings in the lexical environment of the syntax object provided by context-expr. The default context-expr has the same lexical context as the first str-expr. When line-number-expr is true, line number is enabled starting from line-number-expr, and line-number-sep-expr controls the separation (in spaces; defaults to 1) between the line numbers and code.
When expand-expr produces a procedure, it is used to macro-expand the parsed program, and syntax coloring is based on the parsed program.
For example,
@codeblock|{ #lang scribble/manual @codeblock{ #lang scribble/manual @title{Hello} } }|
produces the typeset result
#lang scribble/manual @codeblock{ #lang scribble/manual @title{Hello} }
syntax
(codeblock0 option ... str-expr ...+)
syntax
(code option ... str-expr ...+)
option = #:lang lang-line-expr | #:expand expand-expr | #:context context-expr
lang-line-expr : (or/c #f string?)
expand-expr : (or/c #f (syntax? . -> . syntax?))
context-expr : (or/c #f syntax?)
For example,
This is @code[#:lang "at-exp racket"]|{@bold{Hi}}|'s result: @bold{Hi}.
produces the typeset result
This is @bold{Hi}’s result: Hi.
procedure
(typeset-code [ #:context context #:expand expand #:indent indent #:keep-lang-line? keep? #:line-numbers line-numbers #:line-number-sep line-number-sep #:block? return-block?] strs ...) → (if return-block? block? element?) context : (or/c #f syntax?) = #f expand : (or/c #f (syntax? . -> . syntax?)) = #f indent : exact-nonnegative-integer? = 2 keep? : any/c = #t line-numbers : (or/c #f exact-nonnegative-integer?) = #f line-number-sep : exact-nonnegative-integer? = 1 return-block? : any/c = #t strs : string?
Unlike codeblock, the default context argument (#f) implies that the context is untouched and the return-block? argument determines the result structure. The other arguments are treated the same way as codeblock.
4.2.1.2 Racket Code
syntax
(racketblock maybe-escape datum ...)
maybe-escape =
| #:escape escape-id
(racketblock (define (loop x) (loop (not x))))
produces the output
(define (loop x) (loop (not x)))
with the (loop (not x)) indented under define, because that’s the way it is idented the use of racketblock. Source-location span information is used to preserve #true versus #t and #false versus #f; span information is also used heuristically to add #i to the start of an inexact number if its printed form would otherwise be two characters shorter than the source; syntax-object properties are used to preserve square brackets and curly braces versus parentheses; otherwise, using syntax objects tends to normalize the form of S-expression elements, such as rendering 2/4 as 1/2. When source-location information is not available, such as when it is lost by bytecode-compiled macros, spacing is inserted in the same style (within a single line) as the racket form.
See also quote-syntax/keep-srcloc for use in a macro to preserve source-location information in a template.
In the above example, define is typeset as a keyword (in black) and as a hyperlink to define’s definition in the reference manual, because this document was built using a for-label binding of define (in the source) that matches a definition in the reference manual. Similarly, not is a hyperlink to its definition in the reference manual.
Like other forms defined via define-code, racketblock expands identifiers that are bound as element transformers.
An #:escape clause specifies an identifier to escape back to an expression that produces an element. By default, the escape identifier is unsyntax. For example,
(racketblock (+ 1 #,(elem (racket x) (subscript "2"))))
produces
(+ 1 x2)
The escape-id that defaults to unsyntax is recognized via free-identifier=?, so a binding can hide the escape behavior:
(racketblock (let ([unsyntax #f]) (racketblock #'(+ 1 #,x))))
The RACKETBLOCK form’s default escape is UNSYNTAX instead of unsyntax.
A few other escapes are recognized symbolically:
(code:line datum ...) typesets as the sequence of datums (i.e., without the code:line wrapper).
(code:comment content) typesets like content, but colored as a comment and prefixed with a semi-colon. A typical content escapes from Racket-typesetting mode using unsyntax and produces a string, an element using elem, or a paragraph using t:
(code:comment @#,elem{this is a comment})
(Note that @#,foo{...} reads as #,(foo "...").)
(code:comment2 content) is like code:comment, but uses two semi-colons to prefix the comment.
(code:comment# content) is like code:comment, but uses #; to prefix the comment.
(code:contract datum ...) typesets like the sequence of datums (including its coloring), but prefixed with a semi-colon.
(code:contract# datum ...) is like code:contract, but uses #; to prefix the contract.
(code:hilite datum) typesets like datum, but with a background highlight.
(code:quote datum) typesets like (quote datum), but without rendering the quote as '.
_id typesets as id, but colored as a variable (like racketvarfont); this escape applies only if _id has no for-label binding and is not specifically colored as a subform non-terminal via defform, a variable via defproc, etc.
See also scribble/comment-reader.
Changed in version 1.9 of package scribble-lib: Added heuristic for adding #i to inexact numbers.
syntax
(RACKETBLOCK maybe-escape datum ...)
syntax
(racketblock0 maybe-escape datum ...)
syntax
(RACKETBLOCK0 maybe-escape datum ...)
syntax
(racketresultblock maybe-escape datum ...)
syntax
(racketresultblock0 maybe-escape datum ...)
syntax
(RACKETRESULTBLOCK maybe-escape datum ...)
syntax
(RACKETRESULTBLOCK0 maybe-escape datum ...)
Unlike racketblock, racketresultblock and RACKETRESULTBLOCK implement indentation by adding an (hspace 2) to the start of each line, instead of using nested with the 'code-inset style. To get formatting more like racketblock and racketinput, use (nested #:style 'code-inset (racketresultblock0 datum ...)) instead of (racketresultblock datum ...).
syntax
(racketinput maybe-escape datum ...)
syntax
(RACKETINPUT maybe-escape datum ...)
syntax
(racketinput0 maybe-escape datum ...)
syntax
(RACKETINPUT0 maybe-escape datum ...)
syntax
(racketmod maybe-file maybe-escape lang datum ...)
maybe-file =
| #:file filename-expr maybe-escape =
| #:escape escape-id
The source location of lang (relative to the body datums) determines the relative positioning of the #lang line in the typeset output. So, line up lang with the left end of the content code.
If #:file is provided, then the code block is typeset using filebox with filename-expr as the filename argument.
syntax
(racketmod0 maybe-file maybe-escape lang datum ...)
syntax
(racket maybe-escape datum ...)
syntax
(RACKET maybe-escape datum ...)
syntax
(racketresult maybe-escape datum ...)
syntax
(racketid maybe-escape datum ...)
syntax
(schemeblock maybe-escape datum ...)
syntax
(SCHEMEBLOCK maybe-escape datum ...)
syntax
(schemeblock0 maybe-escape datum ...)
syntax
(SCHEMEBLOCK0 maybe-escape datum ...)
syntax
(schemeinput maybe-escape datum ...)
syntax
(schememod lang maybe-escape datum ...)
syntax
(scheme maybe-escape datum ...)
syntax
(SCHEME maybe-escape datum ...)
syntax
(schemeresult maybe-escape datum ...)
syntax
(schemeid maybe-escape datum ...)
4.2.1.3 Preserving Comments
| #reader scribble/comment-reader | package: scribble-lib |
As a reader module, scribble/comment-reader reads a single S-expression that contains ;-based comment lines, and it wraps the comments with code:comment for use with forms like racketblock. More precisely, scribble/comment-reader extends the current reader to adjust the parsing of ;.
For example, within a Scribble document that imports scribble/manual,
@#reader scribble/comment-reader |
(racketblock |
;; This is not a pipe |
(make-pipe) |
) |
generates
; This is not a pipe (make-pipe)
The initial @ is needed above to shift into S-expression mode, so that #reader is recognized as a reader declaration instead of literal text. Also, the example uses (racketblock ....) instead of @racketblock[....] because the @-reader would drop comments within the racketblock before giving scribble/comment-reader a chance to convert them.
The implementation of scribble/comment-reader uses unsyntax to typeset comments. When using scribble/comment-reader with, for instance, RACKETBLOCK, unsyntax does not escape, since RACKETBLOCK uses UNSYNTAX as its escape form. You can declare an escape identifier for scribble/comment-reader with #:escape-id. For example,
@#reader scribble/comment-reader #:escape-id UNSYNTAX |
(RACKETBLOCK |
(define-syntax (m stx) |
(syntax-case stx () |
[(_ x) |
;; Well this was silly |
#`(#,x)])) |
) |
generates
(define-syntax (m stx) (syntax-case stx () [(_ x) ; Well this was silly #`(#,x)]))
4.2.1.4 Code Fonts and Styles
syntax
(racketmodname datum maybe-indirect)
(racketmodname (unsyntax expr) maybe-indirect)
maybe-indirect =
| #:indirect
If #:indirect is specified, then the hyperlink is given the 'indirect-link style property, which makes the hyperlink’s resolution in HTML potentially delayed; see 'indirect-link for link-element.
Changed in version 1.21 of package scribble-lib: Disabled racket-style special treatment of identifiers.
syntax
(racketmodlink datum pre-content-expr ...)
procedure
(racketfont pre-content ...) → element?
pre-content : pre-content?
procedure
(racketplainfont pre-content ...) → element?
pre-content : pre-content?
Added in version 1.6 of package scribble-lib.
procedure
(racketvalfont pre-content ...) → element?
pre-content : pre-content?
procedure
(racketresultfont [ #:decode? decode?] pre-content ...) → element? decode? : boolean? = #t pre-content : pre-content?
procedure
(racketidfont pre-content ...) → element?
pre-content : pre-content?
procedure
(racketvarfont pre-content ...) → element?
pre-content : pre-content?
procedure
(racketkeywordfont pre-content ...) → element?
pre-content : pre-content?
procedure
(racketparenfont pre-content ...) → element?
pre-content : pre-content?
procedure
(racketoptionalfont pre-content ...) → element?
pre-content : pre-content?
Added in version 1.36 of package scribble-lib.
procedure
(racketmetafont pre-content ...) → element?
pre-content : pre-content?
procedure
(racketcommentfont pre-content ...) → element?
pre-content : pre-content?
procedure
(racketerror pre-content ...) → element?
pre-content : pre-content?
procedure
(racketmodfont pre-content ...) → element?
pre-content : pre-content?
procedure
(racketoutput pre-content ...) → element?
pre-content : pre-content?
procedure
pre-content : pre-content?
syntax
(var datum)
syntax
(svar datum)
syntax
(schememodname datum)
(schememodname (unsyntax expr))
syntax
(schememodlink datum pre-content-expr ...)
procedure
(schemefont pre-content ...) → element?
pre-content : pre-content?
procedure
(schemevalfont pre-content ...) → element?
pre-content : pre-content?
procedure
(schemeresultfont pre-content ...) → element?
pre-content : pre-content?
procedure
(schemeidfont pre-content ...) → element?
pre-content : pre-content?
procedure
(schemevarfont pre-content ...) → element?
pre-content : pre-content?
procedure
(schemekeywordfont pre-content ...) → element?
pre-content : pre-content?
procedure
(schemeparenfont pre-content ...) → element?
pre-content : pre-content?
procedure
(schemeoptionalfont pre-content ...) → element?
pre-content : pre-content?
procedure
(schememetafont pre-content ...) → element?
pre-content : pre-content?
procedure
(schemeerror pre-content ...) → element?
pre-content : pre-content?
procedure
(schememodfont pre-content ...) → element?
pre-content : pre-content?
procedure
(schemeoutput pre-content ...) → element?
pre-content : pre-content?
4.2.2 Documenting Modules
syntax
(defmodule maybe-req one-or-multi option ... pre-flow ...)
maybe-req =
| #:require-form content-or-proc-expr one-or-multi = module-spec | #:multi (module-spec ...+) module-spec = module-path | content-expr option = #:module-paths (module-path ...) | #:no-declare | #:use-sources (src-module-path ...) | #:link-target? link-target?-expr | #:indirect | #:lang | #:reader | #:packages (pkg-expr ...)
Each documented module specified as either a module-path (in the sense of require), in which case the module path is typeset using racketmodname, or by a content-expr. The latter case is triggered by the presence of a #:module-paths clause, which provides a plain module-path for each module-spec, and the plain module-path is used for cross-referencing.
If a #:require-form clause is provided and if #:lang and #:reader are not provided, the given expression produces either content to use instead of require for the declaration of the module, or a procedure that takes the typeset module name as an element and returns an element to use for the require form. The #:require-form clause is useful to suggest a different way of accessing the module instead of through require.
Besides generating text, unless #:no-declare appears as an option, this form expands to a use of declare-exporting with module-paths; the #:use-sources clause, if provided, is propagated to declare-exporting. Consequently, defmodule should be used at most once in a section without #:no-declare, though it can be shadowed with defmodules in sub-sections. Use #:no-declare form when you want to provide a more specific list of modules (e.g., to name both a specific module and one that combines several modules) via your own declare-exporting declaration
When #:link-target? is omitted or specified with an expression that produces a true value, then the module-paths are also declared as link targets though a part-tag-decl (which means that the defmodule form must appear before any sub-parts). These link targets are referenced via racketmodname, which thus points to the enclosing section, rather than the individual module-paths.
Specifying #:indirect normally makes sense only when #:link-target? is specified with a #f value. Specifying #:indirect makes the module path that is displayed (and that normally refers to some other declaration of the module) use racketmodname with #:indirect.
If #:lang is provided as an option, then the module name is shown after #lang (instead of in a require form) to indicate that the module-paths are suitable for use by either require or #lang. If the module path for require is syntactically different from the #lang form, use #:module-paths to provide the require variant (and make each module-spec a content-expr).
If #:reader is provided, then the module name is shown after #reader to indicate that the module path is intended for use as a reader module.
By default, the package (if any) that supplies the documented module is determined automatically, but a set of providing packages can be specified explicitly with #:packages. Each pkg-expr result is passed on to a function like tt for typesetting. Provide an empty sequence after #:packages to suppress any package name in the output. Each pkg-expr expression is duplicated for a declare-exporting form, unless #:no-declare is specified.
Each option form can appear at most once, and #:lang and #:reader are mutually exclusive.
The decoded pre-flows introduce the module, but need not include all of the module content.
Changed in version 1.43 of package scribble-lib: Support a procedure value for #:require-form.
syntax
(declare-exporting module-path/escape ... maybe-pkgs maybe-sources)
maybe-pkgs =
| #:packages (pkg-expr ...) maybe-sources =
| #:use-sources (module-path/escape ...) module-path/escape = module-path | ,module-path-expr
More significantly, the first module-path before #:use-sources plus the module-paths after #:use-sources determine the binding that is documented by each defform, defproc, or similar form within the section that contains the declare-exporting declaration:
If no #:use-sources clause is supplied, then the documentation applies to the given name as exported by the first module-path.
If #:use-sources module-paths are supplied, then they are tried in order before the first module-path. The module-path that provides an export with the same symbolic name and free-label-identifier=? to the given name is used as the documented binding. This binding is assumed to be the same as the identifier as exported by the first module-path in the declare-exporting declaration.
Use #:use-sources sparingly, but it is needed when
bindings are documented as originating from a module M, but the bindings are actually re-exported from some module P; and
other documented modules also re-export the bindings from P, but they are documented as re-exporting from M.
For example, the parameterize binding of mzscheme is documented as re-exported from racket/base, but parameterize happens to be implemented in a private module and re-exported by both racket/base and mzscheme. Importing parameterize from mzscheme does not go through racket/base, so a search for documentation on parameterize in mzscheme would not automatically connect to the documentation of racket/base. To make the connection, the documentation of racket/base declares the private module to be a source through #:use-sources, so that any re-export of parameterize from the private module connects to the documentation for racket/base (unless a re-export has its own documentation, which would override the automatic connection when searching for documentation).
The initial module-paths sequence can be empty if module-paths are given with #:use-sources. In that case, the rendered documentation never reports an exporting module for identifiers that are documented within the section, but the module-paths in #:use-sources provide a binding context for connecting (via hyperlinks) definitions and uses of identifiers.
Supply #:packages to specify the package that provides the declared modules, which is otherwise inferred automatically from the first module-path. The package names are used, for example, by history.
The declare-exporting form should be used no more than once per section, since the declaration applies to the entire section, although overriding declare-exporting forms can appear in sub-sections.
Changed in version 1.1 of package scribble-lib: Added #:packages clause.
Changed in version 1.17: Added support for ,module-path-expr.
syntax
(defmodulelang one-or-multi maybe-sources option ... pre-flow ...)
(defmodulelang one-or-multi #:module-path module-path option ... pre-flow ...)
syntax
(defmodulereader one-or-multi option ... pre-flow ...)
syntax
(defmodule* maybe-req (module-spec ...+) option ... pre-flow ...)
syntax
(defmodulelang* (module-spec ...+) option ... pre-flow ...)
syntax
(defmodulereader* (module-spec ...+) option ... pre-flow ...)
syntax
(defmodule*/no-declare maybe-req (module-spec ...) option ... pre-flow ...)
syntax
(defmodulelang*/no-declare (module-spec ...) option ... pre-flow ...)
syntax
(defmodulereader*/no-declare (module-spec ...) option ... pre-flow ...)
4.2.3 Documenting Forms, Functions, Structure Types, and Values
syntax
(defproc options prototype result-contract-expr-datum maybe-value pre-flow ...)
prototype = (id arg-spec ...) | (prototype arg-spec ...) arg-spec = (arg-id contract-expr-datum) | (arg-id contract-expr-datum default-expr) | (keyword arg-id contract-expr-datum) | (keyword arg-id contract-expr-datum default-expr) | ellipses | ellipses+ options = maybe-kind maybe-link maybe-id maybe-kind =
| #:kind kind-content-expr maybe-link =
| #:link-target? link-target?-expr maybe-id =
| #:id [src-id dest-id-expr] maybe-value =
| #:value value-expr-datum ellipses = ... ellipses+ = ...+
@defproc[(make-sandwich [ingredients (listof ingredient?)]) sandwich?]{ Returns a sandwich given the right ingredients. } @defproc[#:kind "sandwich-maker" (make-reuben [ingredient sauerkraut?] ... [#:veggie? veggie? any/c #f]) sandwich?]{ Produces a reuben given some number of @racket[ingredient]s. If @racket[veggie?] is @racket[#f], produces a standard reuben with corned beef. Otherwise, produces a vegetable reuben. }
Renders like:
procedure
(make-sandwich ingredients) → sandwich?
ingredients : (listof ingredient?) Returns a sandwich given the right ingredients.
sandwich-maker
(make-reuben ingredient ... [ #:veggie? veggie?]) → sandwich? ingredient : sauerkraut? veggie? : any/c = #f Produces a reuben given some number of ingredients.If veggie? is #f, produces a standard reuben with corned beef. Otherwise, produces a vegetable reuben.
When id is indexed and registered, a defmodule or declare-exporting form (or one of the variants) in an enclosing section determines the id binding that is being defined. The id should also have a for-label binding (as introduced by (require (for-label ....))) that matches the definition binding; otherwise, the defined id will not typeset correctly within the definition.
Each arg-spec must have one of the following forms:
(arg-id contract-expr-datum) An argument whose contract is specified by contract-expr-datum which is typeset via racketblock0.
(arg-id contract-expr-datum default-expr) Like the previous case, but with a default value. All arguments with a default value must be grouped together, but they can be in the middle of required arguments.
(keyword arg-id contract-expr-datum) Like the first case, but for a keyword-based argument.
(keyword arg-id contract-expr-datum default-expr) Like the previous case, but with a default value.
... Any number of the preceding argument. This form is normally used at the end, but keyword-based arguments can sensibly appear afterward. See also the documentation for append for a use of ... before the last argument.
...+ One or more of the preceding argument (normally at the end, like ...).
The result-contract-expr-datum is typeset via racketblock0, and it represents a contract on the procedure’s result.
The decoded pre-flow documents the procedure. In this description, references to arg-ids using racket, racketblock, etc. are typeset as procedure arguments.
The typesetting of all information before the pre-flows ignores the source layout, except that the local formatting is preserved for contracts and default-values expressions. The information is formatted to fit (if possible) in the number of characters specified by the current-display-width parameter.
An optional #:kind specification chooses the decorative label, which defaults to "procedure". A #f result for kind-content-expr uses the default, otherwise kind-content-expr should produce content in the sense of content?. An alternate label should be all lowercase.
If #:id [src-id dest-id-expr] is supplied, then src-id is the identifier as it appears in the prototype (to be replaced by a defining instance), and dest-id-expr produces the identifier to be documented in place of src-id. This split between src-id and dest-id-expr roles is useful for functional abstraction of defproc.
If #:value value-expr-datum is given, value-expr-datum is typeset using racketblock0 and included in the documentation. As a service to readers, please use #:value to document only simple, short functions.
syntax
(defproc* options ([prototype result-contract-expr-datum maybe-value] ...+) pre-flow ...)
When an id has multiple calling cases, either they must be defined with a single defproc*, so that a single definition point exists for the id, or else all but one definition should use #:link-target? #f.
@defproc*[([(make-pb&j) sandwich?] [(make-pb&j [jelly jelly?]) sandwich?])]{ Returns a peanut butter and jelly sandwich. If @racket[jelly] is provided, then it is used instead of the standard (grape) jelly. }
Renders like:
procedure
(make-pb&j) → sandwich?
(make-pb&j jelly) → sandwich? jelly : jelly? Returns a peanut butter and jelly sandwich. If jelly is provided, then it is used instead of the standard (grape) jelly.
syntax
(defform options form-datum maybe-grammar maybe-contracts pre-flow ...)
options = maybe-kind maybe-link maybe-id maybe-literals maybe-kind =
| #:kind kind-content-expr maybe-link =
| #:link-target? link-target?-expr maybe-id =
| #:id id | #:id [id id-expr] maybe-literals =
| #:literals (literal-id ...) maybe-grammar =
| #:grammar ([nonterm-id clause-datum ...+] ...) maybe-contracts =
|
#:contracts ([subform-datum contract-expr-datum] ...)
If #:kind kind-content-expr is supplied, it is used in the same way as for defproc, but the default kind is "syntax".
If #:id [id id-expr] is supplied, then id is the identifier as it appears in the form-datum (to be replaced by a defining instance), and id-expr produces the identifier to be documented. This split between id and id-expr roles is useful for functional abstraction of defform.
Unless link-target?-expr is specified and produces #f, the id (or result of id-expr) is indexed, and it is also registered so that racket-typeset uses of the identifier (with the same for-label binding) are hyperlinked to this documentation. The defmodule or declare-exporting requirements, as well as the binding requirements for id (or result of id-expr), are the same as for defproc.
The decoded pre-flow documents the form. In this description, a reference to any identifier in form-datum via racket, racketblock, etc. is typeset as a sub-form non-terminal. If #:literals clause is provided, however, instances of the literal-ids are typeset normally (i.e., as determined by the enclosing context).
If a #:grammar clause is provided, it includes an auxiliary grammar of non-terminals shown with the id form. Each nonterm-id is specified as being any of the corresponding clause-datums.
If a #:contracts clause is provided, each subform-datum (typically an identifier that serves as a meta-variable in form-datum or clause-datum) is shown as producing a value that must satisfy the contract described by contract-expr-datum. Use #:contracts only to specify constraints on a value produced by an expression; for constraints on the syntax of a subform-datum, use grammar notation instead, possibly through an auxiliary grammar specified with #:grammar.
The typesetting of form-datum, clause-datum, subform-datum, and contract-expr-datum preserves the source layout, like racketblock.
@defform[(sandwich-promise sandwich-expr) #:contracts ([sandwich-expr sandwich?])]{ Returns a promise to construct a sandwich. When forced, the promise will produce the result of @racket[sandwich-expr]. } @defform[#:literals (sandwich mixins) (sandwich-promise* [sandwich sandwich-expr] [mixins ingredient-expr ...]) #:contracts ([sandwich-expr sandwich?] [ingredient-expr ingredient?])]{ Returns a promise to construct a sandwich. When forced, the promise will produce the result of @racket[sandwich-expr]. Each result of the @racket[ingredient-expr]s will be mixed into the resulting sandwich. } @defform[(sandwich-factory maybe-name factory-component ...) #:grammar [(maybe-name (code:line) name) (factory-component (code:line #:protein protein-expr) [vegetable vegetable-expr])]]{ Constructs a sandwich factory. If @racket[maybe-name] is provided, the factory will be named. Each of the @racket[factory-component] clauses adds an additional ingredient to the sandwich pipeline. }
Renders like:
syntax
(sandwich-promise sandwich-expr)
sandwich-expr : sandwich? Returns a promise to construct a sandwich. When forced, the promise will produce the result of sandwich-expr.
syntax
(sandwich-promise* [sandwich sandwich-expr] [mixins ingredient-expr ...])
sandwich-expr : sandwich?
ingredient-expr : ingredient? Returns a promise to construct a sandwich. When forced, the promise will produce the result of sandwich-expr. Each result of the ingredient-exprs will be mixed into the resulting sandwich.
syntax
(sandwich-factory maybe-name factory-component ...)
maybe-name =
| name factory-component = #:protein protein-expr | [vegetable vegetable-expr] Constructs a sandwich factory. If maybe-name is provided, the factory will be named. Each of the factory-component clauses adds an additional ingredient to the sandwich pipeline.
syntax
(defform* options [form-datum ...+] maybe-grammar maybe-contracts pre-flow ...)
@defform*[((call-with-current-sandwich expr) (call-with-current-sandwich expr sandwich-handler-expr))]{ Runs @racket[expr] and passes it the value of the current sandwich. If @racket[sandwich-handler-expr] is provided, its result is invoked when the current sandwich is eaten. }
Renders like:
syntax
(call-with-current-sandwich expr)
(call-with-current-sandwich expr sandwich-handler-expr) Runs expr and passes it the value of the current sandwich. If sandwich-handler-expr is provided, its result is invoked when the current sandwich is eaten.
syntax
(defform/none maybe-kind maybe-literal form-datum maybe-grammar maybe-contracts pre-flow ...)
syntax
(defidform maybe-kind maybe-link id pre-flow ...)
syntax
(defidform/inline id)
(defidform/inline (unsyntax id-expr))
syntax
(defsubform options form-datum maybe-grammar maybe-contracts pre-flow ...)
syntax
(defsubform* options [form-datum ...+] maybe-grammar maybe-contracts pre-flow ...)
syntax
(specform maybe-literals datum maybe-grammar maybe-contracts pre-flow ...)
syntax
(specsubform maybe-literals datum maybe-grammar maybe-contracts pre-flow ...)
The pre-flows list is parsed as a flow that documents the procedure. In this description, a reference to any identifier in datum is typeset as a sub-form non-terminal.
syntax
(specspecsubform maybe-literals datum maybe-grammar maybe-contracts pre-flow ...)
syntax
(defform/subs options form-datum ([nonterm-id clause-datum ...+] ...) maybe-contracts pre-flow ...)
syntax
(defform*/subs options [form-datum ...+] ([nonterm-id clause-datum ...+] ...) maybe-contracts pre-flow ...)
syntax
(specform/subs maybe-literals datum ([nonterm-id clause-datum ...+] ...) maybe-contracts pre-flow ...)
syntax
(specsubform/subs maybe-literals datum ([nonterm-id clause-datum ...+] ...) maybe-contracts pre-flow ...)
syntax
(specspecsubform/subs maybe-literals datum ([nonterm-id clause-datum ...+] ...) maybe-contracts pre-flow ...)
@defform/subs[(sandwich-factory maybe-name factory-component ...) [(maybe-name (code:line) name) (factory-component (code:line #:protein protein-expr) [vegetable vegetable-expr])]]{ Constructs a sandwich factory. If @racket[maybe-name] is provided, the factory will be named. Each of the @racket[factory-component] clauses adds an additional ingredient to the sandwich pipeline. }
Renders like:
syntax
(sandwich-factory maybe-name factory-component ...)
maybe-name =
| name factory-component = #:protein protein-expr | [vegetable vegetable-expr] Constructs a sandwich factory. If maybe-name is provided, the factory will be named. Each of the factory-component clauses adds an additional ingredient to the sandwich pipeline.
syntax
(defparam maybe-link id arg-id contract-expr-datum maybe-value pre-flow ...)
@defparam[current-sandwich sandwich sandwich? #:value empty-sandwich]{ A parameter that defines the current sandwich for operations that involve eating a sandwich. Default value is the empty sandwich. }
Renders like:
parameter
(current-sandwich) → sandwich?
(current-sandwich sandwich) → void? sandwich : sandwich?
= empty-sandwich A parameter that defines the current sandwich for operations that involve eating a sandwich. Default value is the empty sandwich.
syntax
(defparam* maybe-link id arg-id in-contract-expr-datum out-contract-expr-datum maybe-value pre-flow ...)
syntax
(defboolparam maybe-link id arg-id maybe-value pre-flow ...)
syntax
(defthing options id contract-expr-datum maybe-value pre-flow ...)
options = maybe-kind maybe-link maybe-id maybe-kind =
| #:kind kind-content-expr maybe-link =
| #:link-target? link-target?-expr maybe-id =
| #:id id-expr maybe-value =
| #:value value-expr-datum
If #:kind kind-content-expr is supplied, it is used in the same way as for defproc, but the default kind is "value".
If #:id id-expr is supplied, then the result of id-expr is used in place of id.
If #:value value-expr-datum is given, value-expr-datum is typeset using racketblock0 and included in the documentation. Wide values are put on a separate line.
@defthing[moldy-sandwich sandwich?]{ Don't eat this. Provided for backwards compatibility. } @defthing[empty-sandwich sandwich? #:value (make-sandwich empty)]{ The empty sandwich. }
Renders like:
value
moldy-sandwich : sandwich?
Don’t eat this. Provided for backwards compatibility.
value
empty-sandwich : sandwich? = (make-sandwich empty)
The empty sandwich.
syntax
(defthing* options ([id contract-expr-datum maybe-value] ...+) pre-flow ...)
@defthing*[([moldy-sandwich sandwich?] [empty-sandwich sandwich?])]{ Predefined sandwiches. }
Renders like:
value
moldy-sandwich : sandwich?
empty-sandwich : sandwich? Predefined sandwiches.
syntax
(defstruct* maybe-link struct-name ([field-name contract-expr-datum] ...) maybe-mutable maybe-non-opaque maybe-constructor pre-flow ...)
syntax
(defstruct maybe-link struct-name ([field-name contract-expr-datum] ...) maybe-mutable maybe-non-opaque maybe-constructor pre-flow ...)
maybe-link =
| #:link-target? link-target?-expr struct-name = id | (id super-id) maybe-mutable =
| #:mutable maybe-non-opaque =
| #:prefab | #:transparent | #:inspector #f maybe-constructor =
| #:constructor-name constructor-id | #:extra-constructor-name constructor-id | #:omit-constructor
Examples:
@defstruct[sandwich ([protein ingredient?] [sauce ingredient?])]{ A structure type for sandwiches. Sandwiches are a pan-human foodstuff composed of a partially-enclosing bread material and various ingredients. }
Renders like:
struct
(struct sandwich (protein sauce) #:extra-constructor-name make-sandwich) protein : ingredient? sauce : ingredient? A structure type for sandwiches. Sandwiches are a pan-human foodstuff composed of a partially-enclosing bread material and various ingredients.
@defstruct*[burrito ([salsa ingredient?] [tortilla ingredient?])]{ A structure type for burritos. Burritos are a pan-human foodstuff composed of a @emph{fully}-encolosed bread material and various ingredients. }
Renders like:
struct
(struct burrito (salsa tortilla))
salsa : ingredient? tortilla : ingredient? A structure type for burritos. Burritos are a pan-human foodstuff composed of a fully-encolosed bread material and various ingredients.
syntax
(deftogether [def-expr ...+] pre-flow ...)
@deftogether[(@defthing[test-sandwich-1 sandwich?] @defthing[test-sandwich-2 sandwich?])]{ Two high-quality sandwiches. These are provided for convenience in writing test cases }
Renders like:
value
test-sandwich-1 : sandwich?
value
test-sandwich-2 : sandwich?
Two high-quality sandwiches. These are provided for convenience in writing test cases
syntax
(racketgrammar maybe-literals id clause-datum ...+)
maybe-literals =
| #:literals (literal-id ...)
syntax
(racketgrammar* maybe-literals [id clause-datum ...+] ...)
procedure
(defidentifier id [ #:form? form? #:index? index? #:show-libs? show-libs?]) → element? id : identifier? form? : boolean? = #f index? : boolean? = #t show-libs? : boolean? = #t
If form? is a true value, then the identifier is documented as a syntactic form, so that uses of the identifier (normally including id itself) are typeset as a syntactic form.
If index? is a true value, then the identifier is registered in the index.
If show-libs? is a true value, then the identifier’s defining module may be exposed in the typeset form (e.g., when viewing HTML and the mouse hovers over the identifier).
syntax
(schemegrammar maybe-literals id clause-datum ...+)
syntax
(schemegrammar* maybe-literals [id clause-datum ...+] ...)
parameter
(current-display-width w) → void? w : exact-nonnegative-integer?
4.2.4 Documenting Classes and Interfaces
syntax
(defclass maybe-link id super (intf ...) pre-flow ...)
maybe-link =
| #:link-target? link-target?-expr super = super-id | (mixin-id super) intf = intf-id | [#:no-inherit intf-id]
The decoding of the pre-flow sequence should start with general documentation about the class, followed by constructor definition (see defconstructor), and then field and method definitions (see defmethod). In rendered form, the constructor and method specification are indented to visually group them under the class definition.
When an intf-id is specified with #:no-inherit, then the set of inherited methods for id does not include methods from intf-id. Omitting methods in this way can avoid a documentation dependency when no direct reference to a method of intf-id is needed.
Changed in version 1.42 of package scribble-lib: Added #:no-inherit for intf.
syntax
(defclass/title maybe-link id super (intf ...) pre-flow ...)
This form is normally used to create a section to be rendered on its own HTML. The 'hidden style is used because the definition box serves as a title.
Changed in version 1.42 of package scribble-lib: Added #:no-inherit for intf.
syntax
(definterface id (intf ...) pre-flow ...)
Changed in version 1.42 of package scribble-lib: Added #:no-inherit for intf.
syntax
(definterface/title id (intf ...) pre-flow ...)
Changed in version 1.42 of package scribble-lib: Added #:no-inherit for intf.
syntax
(defmixin id (domain-id ...) (range-id ...) pre-flow ...)
Changed in version 1.42 of package scribble-lib: Added #:no-inherit support for domain-id.
syntax
(defmixin/title id (domain-id ...) (range-id ...) pre-flow ...)
syntax
(defconstructor (arg-spec ...) pre-flow ...)
arg-spec = (arg-id contract-expr-datum) | (arg-id contract-expr-datum default-expr)
syntax
(defconstructor/make (arg-spec ...) pre-flow ...)
syntax
(defconstructor*/make [(arg-spec ...) ...] pre-flow ...)
syntax
(defconstructor/auto-super [(arg-spec ...) ...] pre-flow ...)
syntax
(defmethod maybe-mode maybe-link (id arg-spec ...) result-contract-expr-datum pre-flow ...)
maybe-link =
| #:link-target? link-target?-expr maybe-mode =
| #:mode public | #:mode public-final | #:mode override | #:mode override-final | #:mode augment | #:mode augment-final | #:mode extend | #:mode extend-final | #:mode pubment
The maybe-mode specifies whether the method overrides a method from a superclass, and so on. (For these purposes, use #:mode override when refining a method of an implemented interface.) The extend mode is like override, but the description of the method should describe only extensions to the superclass implementation. When maybe-mode is not supplied, it defaults to public.
Changed in version 1.35 of package scribble-lib: Added a check against invalid maybe-mode.
syntax
(defmethod* maybe-mode maybe-link ([(id arg-spec ...) result-contract-expr-datum] ...) pre-flow ...)
syntax
(method class/intf-id method-id)
For-label binding information is used with class/intf-id, but not method-id.
syntax
(xmethod class/intf-id method-id)
syntax
(this-obj)
4.2.5 Documenting Signatures
syntax
(defsignature id (super-id ...) pre-flow ...)
The decoded pre-flows inset under the signature declaration in the typeset output, so no new sections, etc. can be started.
syntax
(defsignature/splice id (super-id ...) pre-flow ...)
procedure
(signature-desc pre-flow ...) → any/c
pre-flow : pre-flow?
syntax
(sigelem sig-id id)
4.2.6 Various String Forms
procedure
pre-content : pre-content?
procedure
pre-content : pre-content?
procedure
pre-content : pre-content?
procedure
pre-content : pre-content?
procedure
pre-content : pre-content?
procedure
pre-content : pre-content?
procedure
pre-content : pre-content?
procedure
pre-content : pre-content?
procedure
pre-content : pre-content?
4.2.7 Links
See also Links.
syntax
(racketlink id #:style style-expr pre-content ...)
(racketlink id pre-content ...)
id : identifier?
pre-content : pre-content?
syntax
(schemelink id pre-content ...)
procedure
(link url pre-content ... [ #:underline? underline? #:style style]) → element? url : string? pre-content : any/c underline? : any/c = #t
style : (or/c style? string? symbol? #f) = (if underline? #f "plainlink")
procedure
(other-manual module-path [ #:underline? underline?]) → element? module-path : module-path? underline? : any/c = #t
procedure
(deftech pre-content ... [ #:key key #:normalize? normalize? #:style? style?]) → element? pre-content : pre-content? key : (or/c string? #f) = #f normalize? : any/c = #t style? : any/c = #t
When key is #f, the content->string result of the decoded pre-content is used as a key for references. If normalize? is true, then the key string is normalized as follows:
The string is case-folded.
A trailing “ies” is replaced by “y”.
A trailing “s” is removed.
Consecutive hyphens and whitespaces are all replaced by a single space.
These normalization steps help support natural-language references that differ slightly from a defined form. For example, a definition of “bananas” can be referenced with a use of “banana”.
If style? is true, then defterm is used on pre-content.
procedure
(tech pre-content ... [ #:key key #:normalize? normalize? #:doc module-path #:tag-prefixes prefixes #:indirect? indirect?]) → element? pre-content : pre-content? key : (or/c string? #f) = #f normalize? : any/c = #t module-path : (or/c module-path? #f) = #f prefixes : (or/c (listof string?) #f) = #f indirect? : any/c = #f
(tech #:doc '(lib "scribblings/reference/reference.scrbl") "blame object")
creates a link to blame object in The Racket Reference. If indirect? is not #f, the link’s resolution in HTML is potentially delayed; see 'indirect-link for link-element.
With the default style files, the hyperlink created by tech is somewhat quieter than most hyperlinks: the underline in HTML output is gray, instead of blue, and the term and underline turn blue only when the mouse is moved over the term.
In some cases, combining both natural-language uses of a term and proper linking can require some creativity, even with the normalization performed on the term. For example, if “bind” is defined, but a sentence uses the term “binding,” the latter can be linked to the former using @tech{bind}ing.
Changed in version 1.46 of package scribble-lib: Added #:indirect? argument.
procedure
(techlink pre-content ... [ #:key key #:normalize? normalize? #:doc module-path #:tag-prefixes prefixes #:indirect? indirect?]) → element? pre-content : pre-content? key : (or/c string? #f) = #f normalize? : any/c = #t module-path : (or/c module-path? #f) = #f prefixes : (or/c (listof string?) #f) = #f indirect? : any/c = #f
Changed in version 1.46 of package scribble-lib: Added #:indirect? argument.
4.2.8 Indexing
See also Indexing for scribble/base.
syntax
(indexed-racket datum ...)
If datum is a quote form, then the quote is removed from the key (so that it’s sorted using its unquoted form).
If datum is a string, then quotes are removed from the key (so that it’s sorted using the string content).
syntax
(indexed-scheme datum ...)
procedure
pre-content : pre-content?
procedure
pre-content : pre-content?
procedure
(indexed-file pre-content ...) → element?
pre-content : pre-content?
procedure
(indexed-envvar pre-content ...) → element?
pre-content : pre-content?
4.2.9 Bibliography
See also scriblib/autobib.
procedure
(bibliography [#:tag tag] entry ...) → part?
tag : string? = "doc-bibliography" entry : bib-entry?
procedure
(bib-entry #:key key #:title title [ #:is-book? is-book? #:author author #:location location #:date date #:url url #:note note]) → bib-entry? key : string? title : (or/c #f pre-content?) is-book? : boolean? = #f author : (or/c #f pre-content?) = #f location : (or/c #f pre-content?) = #f date : (or/c #f pre-content?) = #f url : (or/c #f pre-content?) = #f note : (or/c #f pre-content?) = #f
title is the title of the cited work. It will be surrounded by quotes in typeset form if is-book? is #f, otherwise it is typeset via italic.
author lists the authors. Use names in their usual order (as opposed to “last, first”), and separate multiple names with commas using “and” before the last name (where there are multiple names). The author is typeset in the bibliography as given, or it is omitted if given as #f.
location names the publication venue, such as a conference name or a journal with volume, number, and pages. The location is typeset in the bibliography as given, or it is omitted if given as #f.
date is a date, usually just a year (as a string). It is typeset in the bibliography as given, or it is omitted if given as #f.
url is an optional URL. It is typeset in the bibliography using tt and hyperlinked, or it is omitted if given as #f.
note is an optional comment about the work. It is typeset in the bibliography as given, and appears directly after the date (or URL, if given) with no space or punctuation in between.
Changed in version 1.29 of package scribble-lib: Added the #:note option.
procedure
(bib-entry? v) → boolean?
v : any/c
4.2.10 Version History
syntax
(history clause ...+)
clause = #:added version-expr | #:changed version-expr content-expr
version-expr : valid-version?
content-expr : content?
Normally, history should be used at the end of a defform, defproc, etc., entry, although it may also appear in a section that introduces a module (that has been added to a package). In the case of a changed entry, the content produced by content-expr should normally start with a capital letter and end with a period, but it can be a sentence fragment such as “Added a #:changed form.”
@defthing[tasty-burrito burrito?]{ Compatible with the API of a sandwich, but not legally a sandwich in Massachusetts. @history[#:added "1.0" #:changed "1.1" "Refactored tortilla." #:changed "1.2" @elem{Now includes @emph{guacamole}.}] }
Renders like:
Added in version 1.1 of package scribble-lib.
4.2.11 Miscellaneous
procedure
(t pre-content ...) → paragraph?
pre-content : pre-content?
value
value
value
procedure
(commandline content ...) → paragraph?
content : content?
procedure
(inset-flow pre-flow ...) → nested-flow?
pre-flow : pre-flow?
Using nested with the 'inset style is a prefered alternative.
procedure
(centerline pre-flow ...) → nested-flow?
pre-flow : pre-flow?
Any immediate 'rsquo is converted to 'prime.
Parentheses and sequences of decimal digits in immediate strings are left as-is, but any other immediate string is italicized.
When _ appears before a non-empty sequence of numbers and letters, the sequence is typeset as a subscript.
When ^ appears before a non-empty sequence of numbers and letters, the sequence is typeset as a superscript.
procedure
(deprecated [ #:what what] replacement additional-notes ...) → block? what : content? = "library" replacement : content? additional-notes : content?
procedure
(image/plain filename-relative-to-source pre-element ...) → element? filename-relative-to-source : string? pre-element : any/c
4.2.12 Index-Entry Descriptions
| (require scribble/manual-struct) | package: scribble-lib |
struct
(struct module-path-index-desc () #:extra-constructor-name make-module-path-index-desc)
struct
(struct language-index-desc module-path-index-desc () #:extra-constructor-name make-language-index-desc)
struct
(struct reader-index-desc module-path-index-desc () #:extra-constructor-name make-reader-index-desc)
struct
(struct exported-index-desc (name from-libs) #:extra-constructor-name make-exported-index-desc) name : symbol? from-libs : (listof module-path?)
struct
(struct form-index-desc exported-index-desc () #:extra-constructor-name make-form-index-desc)
struct
(struct procedure-index-desc exported-index-desc () #:extra-constructor-name make-procedure-index-desc)
struct
(struct thing-index-desc exported-index-desc () #:extra-constructor-name make-thing-index-desc)
struct
(struct struct-index-desc exported-index-desc () #:extra-constructor-name make-struct-index-desc)
struct
(struct class-index-desc exported-index-desc () #:extra-constructor-name make-class-index-desc)
struct
(struct interface-index-desc exported-index-desc () #:extra-constructor-name make-interface-index-desc)
struct
(struct mixin-index-desc exported-index-desc () #:extra-constructor-name make-mixin-index-desc)
struct
(struct method-index-desc exported-index-desc ( method-name class-tag) #:extra-constructor-name make-method-index-desc) method-name : symbol? class-tag : tag?
struct
(struct constructor-index-desc exported-index-desc (class-tag) #:extra-constructor-name make-constructor-index-desc) class-tag : tag?
4.2.13 Manual Rendering Style
Using #lang scribble/manual for the main part of a document associates style properties on the doc export to select the Racket manual style for rendering.
A html-defaults style property is added to doc, unless doc’s style already has a html-defaults style property (e.g., supplied to title). Similarly, a latex-default style property is added if one is not already present. Finally, an css-style-addition property is always added.
For HTML rendering:
The document’s prefix file is set to "scribble-prefix.html", as usual, in html-defaults.
The document’s style file is set to "manual-style.css" from the "scribble" collection in html-defaults.
The file "manual-fonts.css" from the "scribble" collection is designated as an additional accompanying file in html-defaults.
The file "manual-racket.css" from the "scribble" collection is added as a css-style-addition.
To obtain this configuration without using #lang scribble/manual, use manual-doc-style.
4.3 Racket
| (require scribble/racket) | package: scribble-lib |
| (require scribble/scheme) | |
syntax
(define-code id typeset-expr)
(define-code id typeset-expr uncode-id) (define-code id typeset-expr uncode-id d->s-expr) (define-code id typeset-expr uncode-id d->s-expr stx-prop-expr)
The supplied typeset-expr expression should produce a procedure that performs the actual typesetting. This expression is normally to-element or to-paragraph. The argument supplied to typeset-expr is normally a syntax object, but more generally it is the result of applying d->s-expr.
The optional uncode-id specifies the default escape from literal code to be recognized by id, and the default for uncode-id is unsyntax. A use of the id form can specify an alternate escape via #:escape, as in racketblock and racket.
The optional d->s-expr should produce a procedure that accepts three arguments suitable for datum->syntax: a syntax object or #f, an arbitrary value, and a vector for a source location. The result should record as much or as little of the argument information as needed by typeset-expr to typeset the code. Normally, d->s-expr is datum->syntax.
The stx-prop-expr should produce a procedure for recording a 'paren-shape property when the source expression uses with id has such a property. The default is syntax-property.
procedure
(to-paragraph v [ #:expr? expr? #:escapes? escapes? #:color? color? #:wrap-elem wrap-elem]) → block? v : any/c expr? : any/c = #f escapes? : any/c = #t color? : any/c = #t wrap-elem : (element? . -> . element?) = (lambda (e) e)
Identifiers that have for-label bindings are typeset and hyperlinked based on definitions declared elsewhere (via defproc, defform, etc.). Unless escapes? is #f, the identifiers code:line, code:comment, code:blank, code:hilite, and code:quote are handled as in racketblock, as are identifiers that start with _.
In addition, the given v can contain var-id, shaped-parens, just-context, or literal-syntax structures to be typeset specially (see each structure type for details), or it can contain element structures that are used directly in the output.
If expr? is true, then v is rendered in expression style, much like print with the print-as-expression parameter set to #t. In that case, for-label bindings on identifiers are ignored, since the identifiers are all quoted in the output. Typically, expr? is set to true for printing result values.
If color? is #f, then the output is typeset without coloring.
The wrap-elem procedure is applied to each element constructed for the resulting block. When combined with #f for color?, for example, the wrap-elem procedure can be used to give a style to an element.
procedure
((to-paragraph/prefix prefix1 prefix suffix) v [ #:expr? expr? #:escapes? escapes? #:color? color? #:wrap-elem wrap-elem]) → block? prefix1 : any/c prefix : any/c suffix : any/c v : any/c expr? : any/c = #f escapes? : any/c = #t color? : any/c = #f wrap-elem : (element? . -> . element?) = (lambda (e) e)
procedure
(to-element v [ #:expr? expr? #:escapes? escapes? #:defn? defn?]) → element? v : any/c expr? : any/c = #f escapes? : any/c = #t defn? : any/c = #f
procedure
(to-element/no-color v [ #:expr? expr? #:escapes? escapes?]) → element? v : any/c expr? : any/c = #f escapes? : any/c = #t
struct
(struct var-id (sym) #:extra-constructor-name make-var-id) sym : (or/c symbol? identifier?)
struct
(struct shaped-parens (val shape) #:extra-constructor-name make-shaped-parens) val : any/c shape : char?
struct
(struct long-boolean (val) #:extra-constructor-name make-long-boolean) val : boolean?
struct
(struct just-context (val context) #:extra-constructor-name make-just-context) val : any/c context : syntax?
struct
(struct literal-syntax (stx) #:extra-constructor-name make-literal-syntax) stx : any/c
procedure
v : any/c
procedure
(make-element-id-transformer proc) → element-id-transformer?
proc : (syntax? . -> . syntax?)
procedure
(variable-id? v) → boolean?
v : any/c
procedure
(make-variable-id sym) → variable-id?
sym : (or/c symbol? identifier?)
value
value
value
value
value
value
value
value
value
value
value
value
value
value
value
value
value
value
value
value
value
4.4 Evaluation and Examples
| (require scribble/example) | package: scribble-lib |
Added in version 1.16 of package scribble-lib.
syntax
(examples option ... datum ...)
option = #:eval eval-expr | #:once | #:escape escape-id | #:label label-expr | #:hidden | #:result-only | #:no-inset | #:no-prompt | #:preserve-source-locations | #:no-result | #:lang language-name
Each keyword option can be provided at most once:
#:eval eval-expr —
Specifies an evaluator, where eval-expr must produce either #f or a sandbox evaluator via make-evaluator or make-module-evaluator with the sandbox-output and sandbox-error-output parameters set to 'string. If eval-expr is not provided or is #f, an evaluator is created using make-base-eval. See also make-eval-factory. #:once —
Specifies that the evaluator should be closed with close-eval after the all datums are evaluated. The #:once option is assumed if #:eval is not specified. #:escape escape-id —
Specifies an escape identifier, as in racketblock. #:label label-expr —
Specifies a label for the examples, which defaults to “Example:” or “Examples:” (depending on the number of datums). A #f value for label-expr suppresses the label. #:hidden —
Specifies that the datums and results should not be typeset, but instead evaluated for a side-effect, and disables eval:error. Typically, this option is combined with #:eval to configure an evaluator. #:result-only —
Specifies that the datum results should be typeset, but not the datums themselves, and implies #:label #f. #:no-result —
Implies #:no-prompt and #:label #f, specifies that no results should be typeset, and disables eval:error. #:no-inset —
Specifies that the examples should be typeset without indentation, i.e., like racketinput0 instead of racketinput. #:no-prompt —
Specifies that each examples should be typeset without a leading prompt, i.e., like racketblock instead of racketinput. A prompt can be omitted from a specific datum by wrapping it with eval:no-prompt. #:preserve-source-locations —
Specifies that the original source locations for each datum should be preserved for evaluation. Preserving source locations can be useful for documenting forms that depend on source locations, such as Redex’s typesetting macros. #:lang —
Implies #:no-result prefixes the typeset datum sequence with a #lang line using language-name as the module’s language.
Certain patterns in datum are treated specially:
A datum of the form (code:line code-datum (code:comment comment-datum ...)) is treated as code-datum for evaluation.
A datum of the form (code:line code-datum ...) evaluates each code-datum, but only the last result is used.
Other uses of code:comment, code:contract, and code:blank are stripped from each datum before evaluation.
A datum of the form (eval:error eval-datum) is treated like eval-datum, but eval-datum is expected to raise an exception, and an error is shown as the evaluation’s result.
A datum of the form (eval:alts show-datum eval-datum) is treated as show-datum for typesetting and eval-datum for evaluation.
A datum of the form (eval:check eval-datum expect-datum) is treated like eval-datum, but check-datum is also evaluated, and an error is raised if they are not equal?.
A datum of the form (eval:result content-expr out-expr err-expr) involves no sandboxed evaluation; instead, the content result of content-expr is used as the typeset form of the result, out-expr is treated as output printed by the expression, and err-expr is error output printed by the expression. The out-expr and/or err-expr can be omitted, in which case they default to empty strings.
Normally, eval:result is used in the second part of an eval:alts combination. Otherwise, content-expr is typeset as the input form (which rarely makes sense for a reader of the example).
A datum of the form (eval:results content-list-expr out-expr err-expr) is treated like an eval:result form, except that content-list-expr should produce a list of content for multiple results of evaluation. As with eval:result, out-expr and err-expr are optional.
A datum of the form (eval:no-prompt eval-datum ...) is treated like (code:line eval-datum ...), but no prompt is shown before the group, and a blank line is added before and after eval-datum and its result.
A datum cannot be a keyword. To specify a datum that is a keyword, wrap it with code:line.
When evaluating a datum produces an error (and datum does not have an eval:error wrapper), an exception is raised by examples.
If the value of current-print in the sandbox is changed from its default value, or if print-as-expression in the sandbox is set to #f, then each evaluation result is formatted to a port by applying (current-print) to the value; the output port is set to a pipe that supports specials in the sense of write-special, and non-character values written to the port are used as content. Otherwise, when the default current-print is in place, result values are typeset using to-element/no-color.
As an example,
#lang scribble/manual @(require racket/sandbox scribble/example) @(define my-evaluator (parameterize ([sandbox-output 'string] [sandbox-error-output 'string] [sandbox-memory-limit 50]) (make-evaluator 'typed/racket/base))) @examples[#:eval my-evaluator (: my-sqr (Real -> Real)) (define (my-sqr x) (* x x)) (my-sqr 42)]
uses an evaluator whose language is typed/racket/base.
procedure
(make-base-eval [ #:pretty-print? pretty-print? #:lang lang] input-program ...) → (any/c . -> . any) pretty-print? : any/c = #t
lang :
(or/c module-path? (list/c 'special symbol?) (cons/c 'begin list?)) = '(begin) input-program : any/c
If pretty-print? is true, the sandbox’s printer is set to pretty-print-handler. In that case, values that are convertible in the sense of convertible? are printed using write-special, except that values that are serializable in the sense of serializable? are serialized for tranfers from inside the sandbox to outside (which can avoid pulling code and support from the sandboxed environment into the document-rendering environment).
Changed in version 1.6 of package scribble-lib: Changed treatment of convertible values that are serializable.
procedure
(make-base-eval-factory mod-paths [ #:pretty-print? pretty-print? #:lang lang]) → (-> (any/c . -> . any)) mod-paths : (listof module-path?) pretty-print? : any/c = #t
lang :
(or/c module-path? (list/c 'special symbol?) (cons/c 'begin list?)) = '(begin)
procedure
(make-eval-factory mod-paths [ #:pretty-print? pretty-print? #:lang lang]) → (-> (any/c . -> . any)) mod-paths : (listof module-path?) pretty-print? : any/c = #t
lang :
(or/c module-path? (list/c 'special symbol?) (cons/c 'begin list?)) = '(begin)
procedure
(make-log-based-eval log-file mode) → (-> any/c any)
log-file : path-string? mode : (or/c 'record 'replay)
If mode is 'record, the evaluator records every interaction to log-file, replacing log-file if it already exists. The result of each interaction must be serializable.
If mode is 'replay, the evaluator uses the contents of log-file instead of actually performing evaluatings. For each interaction, it compares the term to evaluate against the next interaction recorded in log-file. If the term matches, the stored result is returned; if not, the evaluator raises an error indicating that it is out of sync with log-file.
Use make-log-based-eval to document libraries when the embedded examples rely on external features that may not be present or appropriately configured on all machines.
Added in version 1.12 of package scribble-lib.
procedure
(close-eval eval) → (one-of/c "")
eval : (any/c . -> . any)
parameter
→ ((any/c . -> . any) boolean? any/c . -> . any) (scribble-eval-handler handler) → void? handler : ((any/c . -> . any) boolean? any/c . -> . any)
(λ (e) (if (exn? e) (exn-message e) (format "uncaught exception: ~s" e)))
4.4.1 Legacy Evaluation
| (require scribble/eval) | package: scribble-lib |
In addition to the forms listed below, scribble/eval re-exports several functions from scribble/example: make-base-eval make-base-eval-factory, make-eval-factory, make-log-based-eval, close-eval, and scribble-eval-handler.
syntax
(interaction maybe-options datum ...)
maybe-options = maybe-eval | maybe-escape | maybe-no-errors maybe-eval =
| #:eval eval-expr maybe-escape =
| #:escape escape-id maybe-no-errors =
| #:no-errors? no-errors?-expr
the “Examples:” label is always supressed,
exceptions raised during the evaluation of a datum are always rendered as errors, unless #:no-errors? is specified with a true value; and
the #:once option is never implicitly used.
Changed in version 1.14 of package scribble-lib: Added #:no-errors?, eval:no-prompt, and eval:error, and changed code:line to support multiple datums.
syntax
(interaction0 maybe-options datum ...)
Use examples with #:no-indent, instead.
syntax
(interaction/no-prompt maybe-eval maybe-escape datum)
Use examples with #:no-prompt, instead.
syntax
(interaction-eval maybe-eval datum)
Use examples with #:hidden, instead.
syntax
(interaction-eval-show maybe-eval datum)
Use examples with #:result-only, instead.
syntax
(racketblock+eval maybe-eval maybe-escape datum ...)
Use examples with #:no-result, instead.
syntax
(racketblock0+eval maybe-eval maybe-escape datum ...)
Use examples with #:no-result and #:no-indent, instead.
syntax
(racketmod+eval maybe-eval maybe-escape name datum ...)
Use examples with #:lang, instead.
syntax
(def+int maybe-options defn-datum expr-datum ...)
syntax
(defs+int maybe-options (defn-datum ...) expr-datum ...)
Use examples with eval:no-prompt wrappers on definitions, instead.
syntax
(examples maybe-options datum ...)
Use examples from scribble/example, instead.
syntax
(examples* label-expr maybe-options datum ...)
Use examples from scribble/example with the #:label option, instead.
syntax
(defexamples maybe-options datum ...)
Use examples with eval:no-prompt wrappers on definitions, instead.
syntax
(defexamples* label-expr maybe-options datum ...)
Use examples with the #:label option and eval:no-prompt wrappers on definitions, instead.
procedure
(as-examples b) → block?
b : block? (as-examples label b) → block? label : (or/c block? content?) b : block?
syntax
(with-eval-preserve-source-locations expr ...)
Use examples with the #:preserve-source-locations option, instead.
4.5 In-Source Documentation
The scribble/srcdoc and scribble/extract libraries support writing documentation within the documented code along with an export contract, similar to using JavaDoc. With this approach, a single contract specification is used both for the run-time contract and the documentation of an exported binding.
The scribble/srcdoc library provides forms for exporting a binding with associated documentation. The scribble/extract library is used to pull scribble/srcdoc-based documentation into a Scribble document (perhaps for multiple libraries).
Although documentation is written with a library’s implementation when using scribble/srcdoc, the documentation creates no run-time overhead for the library. Similarly, typesetting the documentation does not require running the library. The two phases (run time versus documentation time) are kept separate in much the same way that the module system keeps expansion-time code separate from run-time code, and documentation information is recorded in a submodule to be separately loadable from the enclosing module.
For an example use, see this post at blog.racket-lang.org.
4.5.1 Source Annotations for Documentation
| (require scribble/srcdoc) | package: scribble-lib |
Documentation information generated by scribble/srcdoc forms are accumulated into a srcdoc submodule. The generated submodule is accessed by the bindings of scribble/extract.
syntax
(for-doc require-spec ...)
Typically, a library that uses scribble/srcdoc includes at least (require (for-doc scribble/base scribble/manual)) to get core Racket forms and basic Scribble functions to use in documentation expressions.
Each require-spec is used in a submodule relative to the enclosing submodule. To access other submodules of the enclosing module, use a module path of the form (submod ".." name ...).
syntax
(proc-doc/names id contract arg-specs (desc-expr ...))
arg-specs = ((arg-id ...) ((arg-id default-expr) ...)) | (arg-id ...) contract = (-> arg ... result) | (->* (mandatory ...) (optional ...) result) | (case-> (-> arg ... result) ...) mandatory = contract-expr | keyword contract-expr optional = contract-expr | keyword contract-expr
The arg-spec specifies the names of arguments and the default values, which are not normally written as part of a contract. They are combined with the contract expression to generate the description of the binding in the documentation via defproc. The (arg-id default-expr) pairs specify the names and default values of the optional arguments. If the contract supports optional arguments, then the first arg-specs form must be used, otherwise the second must be used.
The desc-expr is a sequence of documentation-time expressions that
produces prose to describe the exported binding—
The normal requires of the enclosing library are effectively converted into for-label requires when generating documentation, so that identifiers in the contracts are linked to their corresponding documentation. Similarly, any binding that is available in the run-time phase of the enclosing library can be referenced in documentation prose using the racket form.
syntax
(proc-doc id contract maybe-defs (desc-expr ...))
contract = (-> result) | (->i (arg ...) (opt ...) maybe-pre [id res]) | (->i (arg ...) (opt ...) maybe-pre (values [id res] ...)) | (->i (arg ...) (opt ...) #:rest rest [id result-expr]) | (->d (arg ...) () maybe-pre (values [id result] ...)) | (->d (arg ...) () maybe-pre [id result]) | (->d (arg ...) () #:rest id rest [id result]) maybe-pre =
| #:pre (pre-id ...) condition maybe-defs =
| (default-expr default-expr ...)
If the sequence of optional arguments, (opt ...) is empty then the maybe-arg-desc must be not be present. If it is non-empty, then it must have as many default expressions are there are optional arguments.
syntax
(thing-doc id contract-expr (desc-expr ...))
syntax
(parameter-doc id (parameter/c contract-expr) arg-id (desc-expr ...))
syntax
(struct*-doc struct-name ([field-name contract-expr-datum] ...) maybe-omit-constructor maybe-mutable maybe-non-opaque maybe-constructor (desc-expr ...))
maybe-omit-constructor =
| #:omit-constructor
The maybe-mutable, maybe-non-opaque, and maybe-constructor options are as in defstruct.
syntax
(struct-doc struct-name ([field-name contract-expr-datum] ...) maybe-omit-constructor maybe-mutable maybe-non-opaque maybe-constructor (desc-expr ...))
syntax
(form-doc options form-datum maybe-grammar maybe-contracts (desc-expr ...))
options = maybe-kind maybe-link maybe-id maybe-literals maybe-kind =
| #:kind kind-string-expr maybe-link =
| #:link-target? link-target?-expr maybe-id =
| #:id id | #:id [id id-expr] maybe-literals =
| #:literals (literal-id ...) maybe-grammar =
| #:grammar ([nonterm-id clause-datum ...+] ...) maybe-contracts =
|
#:contracts ([subform-datum contract-expr-datum] ...)
See defform for information on options, form-datum, maybe-grammar, and maybe-contracts.
Added in version 1.6 of package scribble-lib.
syntax
(class*-doc id super (intf-id ...) pre-flow)
The id, super, and intf-id expressions have the same meaning as in defclass.
Added in version 1.30 of package scribble-lib.
syntax
(class-doc id super pre-flow)
The id, and super expressions have the same meaning as in defclass.
Added in version 1.30 of package scribble-lib.
syntax
(begin-for-doc form ...)
For example, a definition in begin-for-doc can be referenced by a desc-expr in proc-doc/names.
syntax
Delaying document generation in this way allows (for-doc (for-label ....)) imports that would otherwise create cyclic module dependencies.
To avoid problems with accumulated for-doc imports across modules, generate-delayed-documents declaration should appear before any for-doc import.
syntax
(require/doc require-spec ...)
syntax
(provide/doc spec ...)
4.5.2 Extracting Documentation from Source
| (require scribble/extract) | package: scribble-lib |
syntax
(include-extracted module-path)
syntax
(provide-extracted module-path)
Use this form in combination with include-previously-extracted when documentation from a single source is to be split and typeset among multiple documentation locations. The provide-extracted form extracts the documentation once, and then include-previously-extracted form extracts documentation for specific bindings as needed.
syntax
(include-previously-extracted module-path regexp)
4.6 BNF Grammars
| (require scribble/bnf) | package: scribble-lib |
For example,
@(let ([open @litchar{(}] |
[close @litchar{)}]) |
@BNF[(list @nonterm{expr} |
@nonterm{id} |
@BNF-seq[open @kleeneplus[@nonterm{expr}] close] |
@BNF-seq[open @litchar{lambda} |
open @kleenestar[@nonterm{id}] close |
@nonterm{expr} close] |
@nonterm{val}) |
(list @nonterm{val} |
@BNF-alt[@nonterm{number} @nonterm{primop}]) |
(list @nonterm{id} |
@elem{any name except for @litchar{lambda}})]) |
produces the output
| ‹expr› | ::= | ‹id› |
|
| | | ( ‹expr›+ ) |
|
| | | ( lambda ( ‹id›* ) ‹expr› ) |
|
| | | ‹val› |
| ‹val› | ::= | ‹number› | ‹primop› |
| ‹id› | ::= | any name except for lambda |
See also racketgrammar.
procedure
pre-content : pre-content?
procedure
(BNF-seq-lines elems ...) → block?
elems : (listof content?)
procedure
pre-content : pre-content?
procedure
pre-content : pre-content?
procedure
(kleenestar pre-content ...) → element?
pre-content : pre-content?
procedure
(kleeneplus pre-content ...) → element?
pre-content : pre-content?
procedure
(kleenerange n m pre-content ...) → element?
n : any/c m : any/c pre-content : pre-content?
4.7 Compatibility Libraries
4.7.1 Compatibility Structures And Processing
| (require scribble/struct) | package: scribble-lib |
The following structure types and functions are re-exported directly:
The following structure types are re-exported, but the constructors and some selectors are replaced as documented further below:
part paragraph table itemization compound-paragraph element toc-element target-element toc-target-element toc-target2-element page-target-element redirect-target-element link-element index-element
Several additional compatibility functions and structure types are also exported.
procedure
(make-part tag-prefix tags title-content style to-collect blocks parts) → part? tag-prefix : (or/c false/c string?) tags : (listof tag?) title-content : (or/c false/c list?) style : any/c to-collect : list? blocks : (listof block?) parts : (listof part?)
procedure
(part-title-content p) → list?
p : part?
procedure
(make-versioned-part tag-prefix tags title-content style to-collect blocks parts version) → part? tag-prefix : (or/c false/c string?) tags : (listof tag?) title-content : (or/c false/c list?) style : any/c to-collect : list? blocks : (listof block?) parts : (listof part?) version : string?
procedure
(versioned-part? v) → boolean?
v : any/c
procedure
(make-unnumbered-part tag-prefix tags title-content style to-collect blocks parts) → part? tag-prefix : (or/c false/c string?) tags : (listof tag?) title-content : (or/c false/c list?) style : any/c to-collect : list? blocks : (listof block?) parts : (listof part?)
procedure
(unnumbered-part? v) → boolean?
v : any/c
procedure
(make-paragraph content) → paragraph?
content : list?
procedure
(paragraph-content p) → list?
p : paragraph?
procedure
(make-styled-paragraph content style) → paragraph?
content : list? style : any/c
procedure
(styled-paragraph? v) → boolean?
v : any/c
procedure
(styled-paragraph-style p) → style?
p : paragraph?
procedure
(make-omitable-paragraph content) → paragraph?
content : list?
procedure
(omitable-paragraph? v) → boolean?
v : any/c
procedure
(make-table style blocksss) → table?
style : any/c blocksss : (listof (listof (or/c (listof block?) (one-of/c 'cont))))
procedure
(table-flowss table)
→ (listof (listof (or/c (listof block?) (one-of/c 'cont)))) table : table?
procedure
(make-itemization blockss) → itemization?
blockss : (listof (listof block?))
procedure
(make-styled-itemization style blockss) → itemization?
style : any/c blockss : (listof (listof block?))
procedure
(styled-itemization? v) → boolean?
v : any/c
procedure
i : itemization?
procedure
(make-blockquote style blocks) → nested-flow?
style : any/c blocks : (listof block?)
procedure
(make-auxiliary-table style blocksss) → table?
style : any/c blocksss : (listof (listof (or/c (listof block?) (one-of/c 'cont))))
procedure
(auxiliary-table? v) → boolean?
v : any/c
procedure
(make-compound-paragraph style blocks) → compound-paragraph?
style : any/c blocks : (listof block?)
procedure
(make-element style content) → element?
style : any/c content : list?
procedure
(make-toc-element style content toc-content) → toc-element?
style : any/c content : list? toc-content : list?
procedure
(make-target-element style content tag) → target-element?
style : any/c content : list? tag : tag?
procedure
(make-toc-target-element style content tag) → toc-target-element?
style : any/c content : list? tag : tag?
procedure
(make-toc-target2-element style content tag toc-content) → toc-target2-element? style : any/c content : list? tag : tag? toc-content : content?
procedure
(make-page-target-element style content tag)
→ page-target-element? style : any/c content : list? tag : tag?
procedure
(make-redirect-target-element style content tag alt-path alt-anchor) → redirect-target-element? style : any/c content : list? tag : tag? alt-path : path-string? alt-anchor : string?
procedure
(make-link-element style content tag) → link-element?
style : any/c content : list? tag : tag?
procedure
(make-index-element style content tag plain-seq entry-seq desc) → index-element? style : any/c content : list? tag : tag? plain-seq : (and/c pair? (listof string?)) entry-seq : list? desc : any/c
procedure
v : any/c
procedure
(element-content e) → list?
e : element?
procedure
(element-style e) → element-style?
e : element?
procedure
(make-aux-element style content) → element?
style : any/c content : list?
procedure
(make-hover-element style content text) → element?
style : any/c content : list? text : string?
procedure
(make-script-element style content type script) → element? style : any/c content : list? type : string? script : (or/c path-string? (listof string?))
struct
(struct with-attributes (style assoc) #:extra-constructor-name make-with-attributes) style : any/c assoc : (listof (cons/c symbol? string?))
struct
(struct target-url (addr style) #:extra-constructor-name make-target-url) addr : path-string? style : any/c
struct
(struct image-file (path scale) #:extra-constructor-name make-image-file)
path :
(or/c path-string? (cons/c 'collects (listof bytes?))) scale : real?
procedure
(element->string element) → string?
element : content? (element->string element renderer p info) → string? element : content? renderer : any/c p : part? info : resolve-info?
4.7.2 Compatibility Basic Functions
| (require scribble/basic) | package: scribble-lib |
procedure
(span-class style-name pre-content ...) → element?
style-name : string? pre-content : any/c
procedure
(itemize itm ... [#:style style]) → itemization?
itm : (or/c whitespace? an-item?) style : (or/c style? string? symbol? #f) = #f
5 Literate Programming
Programs written using scribble/lp2 are simultaneously two things: a program and a document describing the program:
When the program is run, all of the chunk expressions are collected and stitched together into a program, and the rest of the module is discarded.
When the program is provided to Scribble—
or used through include-section in another Scribble document with a (submod ... doc) module path— the entire contents of the module are treated like an ordinary Scribble document, where chunks are typeset in a manner similar to codeblock.
For example, consider this program:
#lang scribble/lp2 @(require scribble/manual) Literate programs have chunks of code, like this one: @chunk[<f> (define (f x) <fs-body>)] and this one: @chunk[<fs-body> (* x x)] that, when assembled, produce a complete program, in this case: @racketblock[(define (f x) (* x x))]
When this file is required in the normal manner, it defines a function f that squares its argument, and the documentation is ignored. When it is rendered as a Scribble document, the output looks like this:
Literate programs have chunks of code, like this one:
<f> ::=
(define (f x) <fs-body>) and this one:
<fs-body> ::=(* x x)
that, when assembled, produce a complete program, in this case:
(define (f x) (* x x))
5.1 scribble/lp2 Language
| #lang scribble/lp2 | package: scribble-lib |
More precisely, a module in scribble/lp2 has its racket/base-like content in a doc submodule, which is recognized by tools such as raco scribble. The content of the chunk and CHUNK forms is stitched together as the immediate content of the module.
The chunk and CHUNK content is discovered by first expanding the module as written. The content is collected into a new module, and then the original module content is placed into a doc submodule that is expanded (so that the content is effectively re-expanded). The doc submodule is declared with module*.
To include a scribble/lp2 document named "file.scrbl" into another Scribble document, import the doc submodule:
@include-section[(submod "file.scrbl" doc)]
Added in version 1.8 of package scribble-lib.
Changed in version 1.17: Declared the doc submodule with
module* instead of module.
syntax
(chunk id form ...)
When running the enclosing program, only the code inside the chunks is run; the rest is ignored.
If id is <*>, then this chunk is used as the main chunk in the file. If <*> is never used, then the first chunk in the file is treated as the main chunk. If some chunk is not referenced from the main chunk (possibly indirectly via other chunks that the main chunk references), then it is not included in the program and thus is not run.
The forms are typeset using racketblock, so code:comment, etc., can be used to adjust the output. Those output-adjusting forms are stripped from each form for running the program.
Changed in version 1.17 of package scribble-lib: Strip code:comment, etc., for running.
syntax
(CHUNK id form ...)
5.2 scribble/lp Language
| #lang scribble/lp | package: scribble-lib |
The scribble/lp language effectively binds only chunk and CHUNK, while all other bindings for documentation are taken from the context where lp-include is used.
5.3 scribble/lp-include Module
| (require scribble/lp-include) | package: scribble-lib |
syntax
(lp-include filename)
6 Low-Level Scribble API
6.1 Scribble Layers
Scribble is made of independently usable parts. For example, the Scribble reader can be used in any situation that requires lots of free-form text. You can also skip Scribble’s special reader support, and instead use the document-generation structure directly.
6.1.1 Typical Composition
A Scribble document normally starts
but it could also start
or
The last one introduces the smallest number of typesetting bindings in the document body. Using scribble/base after #lang is the same as using scribble/doc plus (require scribble/base), and using scribble/manual after #lang is the same as using scribble/doc plus (require scribble/manual).
Besides making the file a module, each of the #lang declarations selects the Scribble reader (instead of the usual Racket reader), and it starts the body of the file in “text” mode. The reader layer mostly leaves text alone, but @-forms escape to S-expression mode.
A module written as
#lang scribble/doc |
@(require scribble/manual) |
|
@(define to-be "To Be") |
|
@title{@|to-be| or Not @|to-be|} |
|
@bold{That} is the question. |
Whether 'tis nobler... |
reads as
(module ‹name› scribble/doc (require scribble/manual) "\n" (define to-be "To Be") "\n" "\n" (title to-be " or Not " to-be) "\n" "\n" (bold "That") " is the question." "\n" "Whether 'tis nobler..." "\n")
As shown in this example, the read result is a module whose content mingles text and definitions. The scribble/doc language lifts definitions, requires, and provides to the beginning of the module, while everything else is collected into a document bound to the provided identifier doc. That is, the module is transformed to something like this:
(module ‹name› racket/base (require scribble/decode scribble/manual) (define to-be "To Be") (define doc (decode "\n" "\n" "\n" (title to-be " or Not " to-be) "\n" "\n" (bold "That") " is the question." "\n" "Whether 'tis nobler..." "\n")) (provide doc))
The decode function produces a part structure instance that represents the document. To build the part instance, it inspects its arguments to find a title-decl value created by title to name the part, part-start values created by section to designate sub-parts, etc.
A part is the input to a rendering back-end, such as the HTML renderer. All renderers recognize a fixed structure hierarchy: the content of a part is a flow, which is a sequence of flow elements, such as paragraphs and tables; a table, in turn, consists of a list of list of flows; a paragraph is a list of elements, which can be instances of the element structure type, plain strings, or certain special symbols.
The value bound to doc in the example above is something like
(make-part .... (list "To Be" " or Not " "To Be") ; title .... (make-flow (list (make-paragraph (list (make-element 'bold (list "That")) " is the question." "\n" "Whether " 'rsquo "tis nobler...")))) ....)
Notice that the ' in the input’s 'tis has turned into 'rsquo (rendered as a curly apostrophe). The conversion to use 'rsquo was performed by decode via decode-flow via decode-paragraph via decode-content via decode-string.
In contrast, (make-element 'bold (list "That")) was produced by the bold function. The decode operation is a function, not a syntactic form, and so bold has control over its argument before decode sees the result. Also, decoding traverses only immediate string arguments.
As it turns out, bold also decodes its argument, because the bold function is implemented as
(define (bold . strs) (make-element 'bold (decode-content strs)))
The verbatim function, however, does not decode its content, and instead typesets its text arguments directly.
A document module can construct elements directly using make-element, but normally functions like bold and verbatim are used to construct them. In particular, the scribble/manual library provides many functions and forms to typeset elements and flow elements.
The part structure hierarchy includes built-in element types for setting hyperlink targets and references. Again, this machinery is normally packaged into higher-level functions and forms, such as secref, defproc, and racket.
6.1.2 Layer Roadmap
Working roughly from the bottom up, the Scribble layers are:
scribble/reader: A reader that extends the syntax of Racket with @-forms for conveniently embedding a mixin of text and escapes. See @ Syntax.
scribble/core: A set of document datatypes and utilities that define the basic layout and processing of a document. For example, the part datatype is defined in this layer. See Structures And Processing.
scribble/base-render with scribble/html-render, scribble/latex-render, or scribble/text-render: A base renderer and mixins that generate documents in various formats from instances of the scribble/struct datatypes. See Renderers.
scribble/decode: Processes a stream of text, section-start markers, etc. to produce instances of the scribble/core datatypes. See Decoding Text.
scribble/doclang: A language to be used for the initial import of a module; processes the module top level through scribble/decode, and otherwise provides all of racket/base. See Document Language.
scribble/doc: A language that combines scribble/reader with scribble/doclang. See Document Reader.
scribble/base: A library of basic document operators—
such as title, section, and secref— for use with scribble/decode and a renderer. This library name also can be used as a language, where it combines scribble/doc with the exports of scribble/base. See Base Document Format. scribble/racket: A library of functions for typesetting Racket code. See Racket. These functions are not normally used directly, but instead used through scribble/manual.
scribble/manual: A library of functions for writing Racket documentation; re-exports scribble/base. Also, the scribble/manual-struct library provides types for index-entry descriptions created by functions in scribble/manual. See Manual Forms.
scribble/eval: A library of functions for evaluating code at document-build time, especially for showing examples. See Evaluation and Examples.
scribble/bnf: A library of support functions for writing grammars. See BNF Grammars.
scribble/xref: A library of support functions for using cross-reference information, typically after a document is rendered (e.g., to search). See Cross-Reference Utilities.
scribble/text: A language that uses scribble/reader preprocessing text files.
The scribble command-line utility generates output with a
specified renderer. More specifically, the executable installs a
renderer, loads the modules specified on the command line, extracts
the doc export of each module (which must be an instance of
part), and renders each—
6.2 @ Reader Internals
6.2.1 Using the @ Reader
You can use the reader via Racket’s #reader form:
#reader scribble/reader @foo{This is free-form text!}
or use the at-exp meta-language as described in Adding @-expressions to a Language.
Note that the Scribble reader reads @-forms as S-expressions. This means that it is up to you to give meanings for these expressions in the usual way: use Racket functions, define your functions, or require functions. For example, typing the above into racket is likely going to produce a “reference to undefined identifier” error, unless foo is defined. You can use string-append instead, or you can define foo as a function (with variable arity).
A common use of the Scribble @-reader is when using Scribble as a documentation system for producing manuals. In this case, the manual text is likely to start with
which installs the @ reader starting in “text mode,” wraps the file content afterward into a Racket module where many useful Racket and documentation related functions are available, and parses the body into a document using scribble/decode. See Document Reader for more information.
Another way to use the reader is to use the use-at-readtable function to switch the current readtable to a readtable that parses @-forms. You can do this in a single command line:
racket -ile scribble/reader "(use-at-readtable)"
6.2.2 Syntax Properties
The Scribble reader attaches properties to syntax objects. These properties might be useful in some rare situations.
Forms that Scribble reads are marked with a 'scribble property, and a value of a list of three elements: the first is 'form, the second is the number of items that were read from the datum part, and the third is the number of items in the body part (strings, sub-forms, and escapes). In both cases, a 0 means an empty datum/body part, and #f means that the corresponding part was omitted. If the form has neither parts, the property is not attached to the result. This property can be used to give different meanings to expressions from the datum and the body parts, for example, implicitly quoted keywords:
(define-syntax (foo stx) (let ([p (syntax-property stx 'scribble)]) (printf ">>> ~s\n" (syntax->datum stx)) (syntax-case stx () [(_ x ...) (and (pair? p) (eq? (car p) 'form) (even? (cadr p))) (let loop ([n (/ (cadr p) 2)] [as '()] [xs (syntax->list #'(x ...))]) (if (zero? n) (with-syntax ([attrs (reverse as)] [(x ...) xs]) #'(list 'foo `attrs x ...)) (loop (sub1 n) (cons (with-syntax ([key (car xs)] [val (cadr xs)]) #'(key ,val)) as) (cddr xs))))])))
> @foo[x 1 y (* 2 3)]{blah} >>> (foo x 1 y (* 2 3) "blah")
'(foo ((x 1) (y 6)) "blah")
In addition, the Scribble parser uses syntax properties to mark syntax
items that are not physically in the original source —
(define-syntax (verb stx) (syntax-case stx () [(_ cmd item ...) #`(cmd #,@(let loop ([items (syntax->list #'(item ...))]) (if (null? items) '() (let* ([fst (car items)] [prop (syntax-property fst 'scribble)] [rst (loop (cdr items))]) (cond [(eq? prop 'indentation) rst] [(not (and (pair? prop) (eq? (car prop) 'newline))) (cons fst rst)] [else (cons (datum->syntax-object fst (cadr prop) fst) rst)])))))]))
> @verb[string-append]{ foo bar } "foo\n bar"
6.2.3 Adding @-expressions to a Language
| #lang at-exp | package: at-exp-lib |
For example, #lang at-exp racket/base adds @-reader support to racket/base, so that
#lang at-exp racket/base (define (greet who) @string-append{Hello, @|who|.}) (greet "friend")
reports "Hello, friend.".
In addition to configuring the reader for a module body, at-exp attaches a run-time configuration annotation to the module, so that if it used as the main module, the current-read-interaction parameter is adjusted to use the @-reader readtable extension.
Changed in version 1.2 of package at-exp-lib: Added current-read-interaction run-time configuration.
6.2.4 Interface
| (require scribble/reader) | package: at-exp-lib |
procedure
in : input-port? = (current-input-port)
procedure
(read-syntax [source-name in]) → (or/c syntax? eof-object?)
source-name : any/c = (object-name in) in : input-port? = (current-input-port)
(make-at-readtable #:command-readtable 'dynamic #:datum-readtable 'dynamic)
Changed in version 1.1 of package at-exp-lib: Changed to use 'dynamic for the command and datum readtables.
procedure
(read-inside [in]) → any
in : input-port? = (current-input-port)
procedure
(read-syntax-inside [ source-name in #:command-char command-char]) → (or/c syntax? eof-object?) source-name : any/c = (object-name in) in : input-port? = (current-input-port) command-char : char? = #\@
The given command-char is used to customize the readtable used by the reader, effectively passing it along to make-at-readtable.
Changed in version 1.1 of package at-exp-lib: Changed to use 'dynamic for the command and datum readtables.
procedure
(make-at-readtable [ #:readtable readtable #:command-char command-char #:command-readtable command-readtable #:datum-readtable datum-readtable #:syntax-post-processor syntax-post-proc]) → readtable? readtable : readtable? = (current-readtable) command-char : char? = #\@ command-readtable : (or/c readtable? 'dynamic) = readtable
datum-readtable :
(or/c readtable? boolean? (readtable? . -> . readtable?) 'dynamic) = #t syntax-post-proc : (syntax? . -> . syntax?) = values
readtable —
a readtable to base the @-readtable on. command-char —
the character used for @-forms. command-readtable —
determines the readtable that is extended for reading the command part of an @-form: a readtable —
extended to make | a delimiter instead of a symbol-quoting character 'dynamic —
extends (current-readtable) at the point where a command is parsed to make | a delimiter
datum-readtable —
the readtable used for reading the datum part of an @-form: #t —
uses the constructed @-readtable itself a readtable —
uses the given readtable a readtable-to-readtable function —
called to construct a readtable from the generated @-readtable 'dynamic —
uses (current-readtable) at the point where the datum part is parsed
The idea is that you may want to have completely different uses for the datum part, for example, introducing a convenient key=val syntax for attributes.
syntax-post-proc —
function that is applied on each resulting syntax value after it has been parsed (but before it is wrapped quoting punctuations). You can use this to further control uses of @-forms, for example, making the command be the head of a list: (use-at-readtable #:syntax-post-processor (lambda (stx) (syntax-case stx () [(cmd rest ...) #'(list 'cmd rest ...)] [else (error "@ forms must have a body")])))
Changed in version 1.1 of package at-exp-lib: Added #:command-readtable and the 'dynamic option for #:datum-readtable.
procedure
(make-at-reader #:syntax? syntax? #:inside? inside? ...) → procedure? syntax? : #t inside? : #f
The resulting function has a different contract and action based on these inputs. The expected inputs are as in read or read-syntax depending on syntax?; the function will read a single expression or, if inside? is true, the whole input; it will return a syntactic list of expressions rather than a single one in this case.
Note that syntax? defaults to #t, as this is the more expected common case when you’re dealing with concrete-syntax reading.
procedure
(use-at-readtable ...) → void?
This is mostly useful for playing with the Scribble syntax on the REPL.
6.3 Structures And Processing
| (require scribble/core) | package: scribble-lib |
A document is represented as a part, as described in Parts, Flows, Blocks, and Paragraphs. This representation is intended to be independent of its eventual rendering, and it is intended to be immutable; rendering extensions and specific data in a document can collude arbitrarily, however.
A document is processed in four passes:
The traverse pass traverses the document content in document order so that information from one part of a document can be communicated to other parts of the same document. The information is transmitted through a symbol-keyed mapping that can be inspected and extended by traverse-elements and traverse-blocks in the document. The traverse pass iterates the traversal until it obtains a fixed point (i.e., the mapping from one iteration is unchanged from the previous iteration).
The collect pass globally collects information in the document that can span documents that are built at separate times, such as targets for hyperlinking.
The resolve pass matches hyperlink references with targets and expands delayed elements (where the expansion should not contribute new hyperlink targets).
None of the passes mutate the document representation. Instead, the traverse pass, collect pass, and resolve pass accumulate information in a side hash table, collect-info table, and resolve-info table. The collect pass and resolve pass are effectively specialized version of traverse pass that work across separately built documents.
6.3.1 Parts, Flows, Blocks, and Paragraphs
This diagram shows the large-scale structure of the type hierarchy for Scribble documents. A box represents a struct or a built-in Racket type; for example part is a struct. The bottom portion of a box shows the fields; for example part has three fields, title, blocks, and subparts. The substruct relationship is shown vertically with navy blue lines connected by a triangle; for example, a compound-paragraph is a block. The types of values on fields are shown via dark red lines in the diagram. Doubled lines represent lists and tripled lines represent lists of lists; for example, the blocks field of compound-paragraph is a list of blocks. Dotted lists represent functions that compute elements of a given field; for example, the block field of a traverse-block struct is a function that computes a block.
The diagram is not completely accurate: a table may have 'cont in place of a block in its cells field, and the types of fields are only shown if they are other structs in the diagram. A prose description with more detail follows the diagram.
A part is an instance of part; among other things, it has a title content, an initial flow, and a list of subsection parts. There is no difference between a part and a full document; a particular source module just as easily defines a subsection (incorporated via include-section) as a document.
A flow is a list of blocks.
A block is either a table, an itemization, a nested flow, a paragraph, a compound paragraph, a traverse block, or a delayed block.
A table is an instance of table; it has a list of list of blocks corresponding to table cells.
A itemization is an instance of itemization; it has a list of flows.
A nested flow is an instance of nested-flow; it has a flow that is typeset as sub-flow.
A paragraph is an instance of paragraph; it has a content:
A content can be a string, one of a few symbols, a convertible value in the sense of convertible?, an instance of element (possibly link-element, etc.), a multiarg-element, a traverse element, a part-relative element, a delayed element, or a list of content.
A string is included in the result document verbatim, except for space, and unless the content’s enclosing style is 'hspace. In a style other than 'hspace, consecutive spaces in the output may be collapsed togther or replaced with a line break. In the style 'hspace, all text is converted to uncollapsible spaces that cannot be broken across lines.
A symbol content is either 'mdash, 'ndash, 'ldquo, 'lsquo, 'rdquo, 'rsquo, 'larr, 'rarr, or 'prime; it is rendered as the corresponding HTML entity (even for Latex output).
A convertible value in the sense of convertible? is used in a renderer-specific way, but values convertible to 'text renders the same as the resulting string. If a renderer is not able to convert the value to a known format, the value is converted to a string using write.
An instance of element has a content plus a style. The style’s interpretation depends on the renderer, but it can be one of a few special symbols (such as 'bold) that are recognized by all renderers.
An instance of link-element has a tag for the target of the link.
An instance of target-element has a tag to be referenced by link-elements. An instance of the subtype toc-target-element is treated like a kind of section label, to be shown in the “on this page” table for HTML output.
An instance of index-element has a tag (as a target), a list of strings for the keywords (for sorting and search), and a list of contents to appear in the end-of-document index.
An instance of image-element incorporates an image from a file into the rendered document.
An instance of multiarg-element combines a style with a list of content, where the style corresponds to a rendered command that takes multiple arguments.
An instance of collect-element has a procedure that is called in the collect pass of document processing to record information used by later passes.
A traverse element is an instance of traverse-element, which ultimately produces content, but can accumulate and inspect information in the traverse pass.
A part-relative element is an instance of part-relative-element, which has a procedure that is called in the collect pass of document processing to obtain content. When the part-relative element’s procedure is called, collected information is not yet available, but information about the enclosing parts is available.
A delayed element is an instance of delayed-element, which has a procedure that is called in the resolve pass of document processing to obtain content.
An instance of render-element has a procedure that is called in the render pass of document processing.
A compound paragraph is an instance of compound-paragraph; like blockquote, it has list of blocks, but the blocks are typeset as a single paragraph (e.g., no indentation after the first block) instead of inset.
A traverse block is an instance of traverse-block, which ultimately produces another block, but can accumulate and inspect information during the traverse pass.
A delayed block is an instance of delayed-block, which has a procedure that is called in the resolve pass of document processing to obtain a block.
Changed in version 1.23 of package scribble-lib: Changed the handling of convertible? values to recognize a 'text conversion and otherwise use write.
6.3.2 Tags
A tag is a list containing a symbol and either a string, a generated-tag instance, or an arbitrary list. The symbol effectively identifies the type of the tag, such as 'part for a tag that links to a part, or 'def for a Racket function definition. The symbol also effectively determines the interpretation of the second half of the tag.
A part can have a tag prefix, which is effectively added onto the second item within each tag whose first item is 'part, 'tech, or 'cite, or whose second item is a list that starts with 'prefixable:
The prefix is added to a string second item by creating a list containing the prefix and string.
The prefix is added to a list second item after 'part, 'tech, or 'cite using cons.
The prefix is added to a second item that starts 'prefixable by adding it to the list after 'prefixable.
A prefix is not added to a generated-tag item.
The prefix is used for reference outside the part, including the use of tags in the part’s tags field. Typically, a document’s main part has a tag prefix that applies to the whole document; references to sections and defined terms within the document from other documents must include the prefix, while references within the same document omit the prefix. Part prefixes can be used within a document as well, to help disambiguate references within the document.
Some procedures accept a “tag” that is just the string part of the full tag, where the symbol part is supplied automatically. For example, section and secref both accept a string “tag”, where 'part is implicit.
The scribble/tag library provides functions for constructing tags.
6.3.3 Styles
A style combines a style name with a list of style properties in a style structure. A style name is either a string, symbol, or #f. A style property can be anything, including a symbol or a structure such as color-property.
A style has a single style name, because the name typically corresponds to a configurable instruction to a renderer. For example, with Latex output, a string style name corresponds to a Latex command or environment. For more information on how string style names interact with configuration of a renderer, see Extending and Configuring Scribble Output. Symbolic style names, meanwhile, provide a simple layer of abstraction between the renderer and documents for widely supported style; for example, the 'italic style name is supported by all renderers.
Style properties within a style compose with style names and other properties. Again, symbols are often used for properties that are directly supported by renderers. For example, 'unnumbered style property for a part renders the part without a section number. Many properties are renderer-specific, such as a hover-property structure that associates text with an element to be shown in an HTML display when the mouse hovers over the text.
6.3.4 Collected and Resolved Information
The collect pass, resolve pass, and render pass processing steps all produce information that is specific to a rendering mode. Concretely, the operations are all represented as methods on a render<%> object.
The result of the collect method is a collect-info instance. This result is provided back as an argument to the resolve method, which produces a resolve-info value that encapsulates the results from both iterations. The resolve-info value is provided back to the resolve method for final rendering.
Optionally, before the resolve method is called, serialized information from other documents can be folded into the collect-info instance via the deserialize-info method. Other methods provide serialized information out of the collected and resolved records.
During the collect pass, the procedure associated with a collect-element instance can register information with collect-put!.
During the resolve pass, collected information for a part can be extracted with part-collected-info, which includes a part’s number and its parent part (or #f). More generally, the resolve-get method looks up information previously collected. This resolve-time information is normally obtained by the procedure associated with a delayed block or delayed element.
The resolve-get information accepts both a part and a resolve-info argument. The part argument enables searching for information in each enclosing part before sibling parts.
6.3.5 Structure Reference
struct
(struct part ( tag-prefix tags title-content style to-collect blocks parts) #:extra-constructor-name make-part) tag-prefix : (or/c #f string?) tags : (listof tag?) title-content : (or/c #f list?) style : style? to-collect : list? blocks : (listof block?) parts : (listof part?)
The tags indicates a list of tags that each link to the section. Normally, tags should be a non-empty list, so that hyperlinks can target the section.
The title-content field holds the part’s title, if any.
For the style field, the currently recognized symbolic style names are as follows:
The recognized style properties are as follows:
'unnumbered —
A section number is not computed or rendered for the section. 'hidden-number —
A section number is computed for the section, but it is not rendered as part of the section name. 'toc-hidden —
The part title is not shown in tables of contents, including in “on this page” boxes. For Latex rendering, the part title is omitted only if it is unnumbered or has a hidden number. 'hidden —
The part title is not shown; for Latex output, the part title is not shown only if its is empty, and in that case, it is also excluded from tables of contents. The 'toc-hidden style property usually should be included with 'hidden (for consistency in non-Latex output). 'grouper —
The part is numbered with a Roman numeral, by default, and its subsections continue numbering as if they appeared in the preceeding part. In other words, the part acts like a “part” in a book where chapter numbering is continuous across parts. numberer —
A numberer created with make-numberer determines a representation of the part’s section number as an extension of it’s parent’s number. A numberer overrides the default representation, which is a natural number or (in the case of an accompanying 'grouper property) a Roman numeral. If a 'unnumbered property is also present, a numberer property is ignored. 'toc —
Sub-parts of the part are rendered on separate pages for multi-page HTML mode. 'non-toc —
Initial sub-parts of the part are not rendered on separate pages for multi-page HTML mode; this style property applies only to the main part. 'reveal —
Shows sub-parts when this part is displayed in a table-of-contents panel in HTML output (which normally shows only the top-level sections). 'quiet —
In HTML output and most other output modes, hides entries for sub-parts of this part in a table-of-contents or local-table-of-contents listing except when those sub-parts are top-level entries in the listing. 'no-toc+aux —
As a style property for the main part of a rendered page, causes the HTML output to not include a margin box for the main table of contents, “on this page”, or tables with the 'aux style property. The 'no-toc+aux property effectively implies 'no-toc and 'no-sidebar, but also suppresses 'aux tables. 'no-toc —
As a style property for the main part of a rendered page, causes the HTML output to not include a margin box for the main table of contents; the “on this page” box that contains toc-element and toc-target-element links (and that only includes an “on this page” label for multi-page documents) takes on the location and color of the main table of contents, instead. 'no-sidebar —
As a style property for the main part of a document, causes the HTML output to not include an “on this page” margin box. 'no-index —
Has no effect as a style property on a part, but as a style property on a title or part-start that provides a part’s style via decode, the 'no-index style property cause decode to skip the generation of an entry for the part’s title in the document index. document-version structure —
A version number for this part and its sub-parts (except as overridden). When it is not "" may be used when rendering a document; at a minimum, a non-"" version is rendered when it is attached to a part representing the whole document. The default version for a document is (version). In rendered form, the version is normally prefixed with the word “Version,” but this formatting can be controlled by overriding .version:before and/or .versionNoNav:before in CSS for HTML rendering or by redefining the \SVersionBefore macro for Latex rendering (see Extending and Configuring Scribble Output). document-date structure —
A date for the part, normally used on a document’s main part for for Latex output. The default date for a document is #f, which avoids explicitly specifying a date at the Latex level, so that the current date is used as the document date. Set the date to "" to suppress a date in an output document. body-id structure —
Generated HTML uses the given string id attribute of the <body> tag; this style property can be set separately for parts that start different HTML pages, otherwise it is effectively inherited by sub-parts; the default is "scribble-racket-lang.org", but raco setup installs "doc-racket-lang.org" as the id for any document that it builds. attributes structure —
Provides additional HTML attributes for the <html> tag when the part corresponds to its own HTML page. head-extra structure —
Provides additional HTML content for the <head> tag when the part corresponds to its own HTML page. color-property structure —
For HTML, applies a color to the part title. background-color-property structure —
For HTML, applies a color to the background of the part title. hover-property structure —
For HTML, adds a text label to the title to be shown when the mouse hovers over it. render-convertible-as structure —
For HTML, controls how objects that subscribe to the file/convertible protocol are rendered. document-source structure —
For HTML, provides a module path for the part’s source. Clicking on an HTML section title generated for the part or its sub-parts may show the module path plus a section-tag string, so that the user can create a reference to the section. link-render-style structure —
Determines the default rendering of links to sections or other destinations within the section. See also link-element and current-link-render-style. 'enable-index-merge —
On an index parts or one of its enclosing parts for Latex output, causes index entries to be merged when they have the same content, with multiple references for the same entry combined with \Smanypageref. The \Smanypageref Latex macro must be redefined to accept multiple ,-separated labels and generate a suitable set of references. See also scriblib/book-index.
The to-collect field contains content that is inspected during the collect pass, but ignored in later passes (i.e., it doesn’t directly contribute to the output).
The blocks field contains the part’s initial flow (before sub-parts).
The parts field contains sub-parts.
Changed in version 1.25 of package scribble-lib: Added 'no-index support.
Changed in version 1.26: Added link-render-style support.
Changed in version 1.27: Added 'no-toc+aux support.
struct
(struct paragraph (style content) #:extra-constructor-name make-paragraph) style : style? content : content?
For the style field, a string style name corresponds to a CSS class for HTML output or a macro for Latex output (see Implementing Styles). The following symbolic style names are recognized:
'author —
Typeset as the author of a document. Such paragraphs normally should appear only in the initial flow of a part for a document, where they are treated specially by the Latex renderer by moving the author information to the title. 'wraps —
Like a #f style name, but not boxable in the sense of box-mode for Latex output.
When a paragraph’s style is #f, then it is boxable in the sense of box-mode for Latex output.
The currently recognized style properties are as follows:
'omitable —
When a table cell contains a single paragraph with the 'omitable style property, then when rendering to HTML, no <p> tag wraps the cell content. 'div —
Generates <div> HTML output instead of <p> (unless a alt-tag property is provided). alt-tag structure —
Generates the indicated HTML tag instead of <p> or <div>. attributes structure —
Provides additional HTML attributes for the <p>, <div>, or alternate tag. 'never-indents —
For Latex and compound paragraphs; see compound-paragraph. box-mode structure —
For Latex output, uses an alternate rendering form for boxing contexts (such as a table cell); see box-mode.
struct
(struct table (style blockss) #:extra-constructor-name make-table) style : style? blockss : (listof (listof (or/c block? 'cont)))
A table has, roughly, a list of list of blocks. A cell in the table can span multiple columns by using 'cont instead of a block in the following columns (i.e., for all but the first in a set of cells that contain a single block).
Within style, a string style name corresponds to a CSS class for HTML output or an environment for Latex output (see Implementing Styles). The following symbolic style names are also recognized:
'boxed —
Renders as a definition. This style name is not intended for use on a table that is nested within a 'boxed table; nested uses may look right for some renders of the style but not others.
The following style properties are currently recognized:
table-columns structure —
Provides column-specific styles, but only column-attributes properties (if any) are used if a table-cells structure is included as a style property. See table-cells for information about how a column style is used for each cell. table-cells structure —
Provides cell-specific styles. See table-cells for information about how the styles are used. attributes structure —
Provides additional HTML attributes for the <table> tag. 'aux —
For HTML, include the table in the table-of-contents display for the enclosing part. 'never-indents —
For Latex and compound paragraphs; see compound-paragraph.
For Latex output, a paragraph as a cell value is not automatically line-wrapped, unless a vertical alignment is specified for the cell through a table-cells or table-columns style property. To get a line-wrapped paragraph, use a compound-paragraph or use an element with a string style and define a corresponding Latex macro in terms of \parbox. For Latex output of blocks in the flow that are nested-flows, itemizations, compound-paragraphs, or delayed-blocks, the block is wrapped with minipage using \linewidth divided by the column count as the width.
struct
(struct itemization (style blockss) #:extra-constructor-name make-itemization) style : style? blockss : (listof (listof block?))
In style, a string style name corresponds to a CSS class for HTML output or a macro for Latex output (see Implementing Styles). In addition, the following symbolic style names are recognized:
'ordered —
Generates <ol> HTML output instead of <ul> or an Latex enumeration instead of an itemization.
The following style properties are currently recognized:
attributes structure —
Provides additional HTML attributes for the <ul> or <ol> tag. 'never-indents —
For Latex and compound paragraphs; see compound-paragraph.
struct
(struct nested-flow (style blocks) #:extra-constructor-name make-nested-flow) style : style? blocks : (listof block?)
In style, the style name is normally a string that corresponds to a CSS class for HTML <blockquote> output or a Latex environment (see Implementing Styles). The following symbolic style names are recognized:
'inset —
Insets the nested flow relative to surrounding text. 'code-inset —
Insets the nested flow relative to surrounding text in a way suitable for code. If the nested flow has a single block, then it is boxable in the sense of box-mode for Latex output. 'vertical-inset —
Insets the nested flow vertically relative to surrounding text, but not horizontally. If the nested flow has a single block, then it is boxable in the sense of box-mode for Latex output.
The following style properties are currently recognized:
'command —
For Latex output, a string style name is used as a command name instead of an environment name. 'multicommand —
For Latex output, a string style name is used as a command name with a separate argument for each block in blocks. attributes structure —
Provides additional HTML attributes for the <blockquote> tag. 'never-indents —
For Latex and compound paragraphs; see compound-paragraph. box-mode structure —
For Latex output, uses an alternate rendering form for boxing contexts (such as a table cell); see box-mode. 'decorative —
The content of the nested flow is intended for decoration. Text output skips a decorative nested flow. alt-tag structure —
Generates the indicated HTML tag instead of <blockquote>. 'pretitle —
For Latex, raises the contents of the flow to above the title.
struct
(struct compound-paragraph (style blocks) #:extra-constructor-name make-compound-paragraph) style : style? blocks : (listof block?)
For HTML, a paragraph block in blocks is rendered without a <p> tag, unless the paragraph has a style with a non-#f style name. For Latex, each block in blocks is rendered with a preceding \noindent, unless the block has the 'never-indents property (checking recursively in a nested-flow or compound-paragraph if the nested-flow or compound-paragraph itself has no 'never-indents property).
The style field of a compound paragraph is normally a string that corresponds to a CSS class for HTML output or Latex environment for Latex output (see Implementing Styles). The following style properties are currently recognized:
'command —
For Latex output, a string style name is used as a command name instead of an environment name. alt-tag structure —
Generates the given HTML tag instead of <p>. attributes structure —
Provides additional HTML attributes for the <p> or alternate tag. 'never-indents —
For Latex within another compound paragraph; see above.
struct
(struct traverse-block (traverse) #:extra-constructor-name make-traverse-block) traverse : block-traverse-procedure/c
The traverse procedure is called with get and set procedures to get and set symbol-keyed information; the traverse procedure should return either a block (which effectively takes the traverse-block’s place) or a procedure like traverse to be called in the next iteration of the traverse pass.
All traverse-element and traverse-blocks that have not been replaced are forced in document order relative to each other during an iteration of the traverse pass.
The get procedure passed to traverse takes a symbol and any value to act as a default; it returns information registered for the symbol or the given default if no value has been registered. The set procedure passed to traverse takes a symbol and a value to be registered for the symbol.
See also cond-block in scriblib/render-cond. The symbol 'scribble:current-render-mode is automatically registered to a list of symbols that describe the target of document rendering. The list contains 'html when rendering to HTML, 'latex when rendering via Latex, and 'text when rendering to text. The registration of 'scribble:current-render-mode cannot be changed via set.
struct
(struct delayed-block (resolve) #:extra-constructor-name make-delayed-block) resolve : (any/c part? resolve-info? . -> . block?)
struct
(struct element (style content) #:extra-constructor-name make-element) style : element-style? content : content?
The style field can be a style structure, but it can also be just a style name.
In style, a string style name corresponds to a CSS class for HTML output and a macro name for Latex output (see Implementing Styles). The following symbolic style names are recognized:
'tt, 'italic, 'bold, 'roman, 'sf, 'url, 'subscript, 'superscript, 'smaller, 'larger —
Basic styles recognized by all renders.
The following style properties are currently recognized:
target-url structure —
Generates a hyperlink. url-anchor structure —
For HTML, inserts a hyperlink target before content. color-property structure —
Applies a color to the text of content. background-color-property structure —
Applies a color to the background of content. alt-tag structure —
Generates the given HTML tag instead of the default one (<span>, <b>, etc.). attributes structure —
Provides additional HTML attributes for a tag. hover-property structure —
For HTML, adds a text label to the content to be shown when the mouse hovers over it. script-property structure —
For HTML, supplies a script alternative to content. xexpr-property structure —
For HTML, supplies literal HTML to render before and after content. 'aux —
Intended for use in titles, where the auxiliary part of the title can be omitted in hyperlinks. See, for example, secref. 'tt-chars —
For Latex output, when the style name is a string, render the element’s content with escapes suitable for Latex tt mode. 'exact-chars —
For Latex output, when the style name is a string or #f, render the elements content exactly (without escapes). command-extras structure —
For Latex output, adds strings as arguments to the Latex command.
Changed in version 1.6 of package scribble-lib: Changed 'exact-chars handling to
take effect when the style name is #f.
Changed in version 1.27: Changed to support xexpr-property.
struct
(struct image-element element (path suffixes scale) #:extra-constructor-name make-image-element)
path :
(or/c path-string? (cons/c 'collects (listof bytes?))) suffixes : (listof #rx"^[.]") scale : real?
For each string in suffixes, if the rendered works with the corresponding suffix, the suffix is added to path and used if the resulting path refers to a file that exists. The order in suffixes determines the order in which suffixes are tried. The HTML renderer supports ".png", ".gif", and ".svg", while the Latex renderer supports ".png", ".pdf", and ".ps" (but rendering Latex output to PDF will not work with ".ps" files, while rendering to Latex DVI output works only with ".ps" files). If suffixes is empty or if none of the suffixes lead to files that exist, path is used as-is.
The scale field scales the image in its rendered form.
struct
(struct target-element element (tag) #:extra-constructor-name make-target-element) tag : tag?
struct
(struct toc-target-element target-element () #:extra-constructor-name make-toc-target-element)
struct
(struct toc-target2-element toc-target-element (toc-content) #:extra-constructor-name make-toc-target2-element) toc-content : content?
struct
(struct page-target-element target-element () #:extra-constructor-name make-page-target-element)
struct
(struct redirect-target-element target-element ( alt-path alt-anchor) #:extra-constructor-name make-redirect-target-element) alt-path : path-string? alt-anchor : string?
struct
(struct toc-element element (toc-content) #:extra-constructor-name make-toc-element) toc-content : content?
struct
(struct link-element element (tag) #:extra-constructor-name make-link-element) tag : tag?
Normally, the content of the element is rendered as the hyperlink. When tag is a part tag and the content of the element is null, however, rendering is treated specially based on the mode value of a link-render-style style property:
For HTML output, in the 'default mode, the generated reference is the hyperlinked title of the elements in the section’s title content, except that elements with the 'aux style property are omitted in the hyperlink label.
In 'number mode, the section title is not shown. Instead, the word “section” is shown followed by a hyperlinked section number. The word “section” starts in uppercase if the element’s style includes a 'uppercase property.
For Latex/PDF output, the generated reference’s format can depend on the document style in addition the mode. For the 'default mode and a default document style, a section number is shown by the word “section” followed by the section number, and the word “section” and the section number are together hyperlinked. The word “section” starts in uppercase if the element’s style includes a 'uppercase property. The scribble/manual style uses the symbol “§” in place of the word “section”.
In 'number mode, rendering is the same, except that only the number is hyperlinked, not the word “section” or the “§” symbol.
A new document style can customize Latex/PDF output (see Extending and Configuring Scribble Output) by redefining the \SecRefLocal, etc., macros (see Base Latex Macros). The \SecRef, etc., variants are used in 'number mode.
If a link-render-style style property is not attached to a link-element that refers to a part, a link-render-style style property that is attached to an enclosing part is used, since attaching a link-render-style style property to a part causes current-link-render-style to be set while rendering the part. Otherwise, the render-time value of current-link-render-style determine’s a link-element’s rendering.
The following style properties are recognized in addition to the style properties for all elements:
link-render-style structure —
As described above. 'indirect-link —
For HTML output, treats the link as “external”. When rendering to HTML and the set-external-tag-path method is called to provide an external-link URL, then the resolution of the hyperlink can be deferred until the link is clicked (or, in some cases, patched by JavaScript when the documentation is viewed in a browser). Note that deferred resolution relies on cooperation with the page pointed to by the external-link URL, and arbitrary tags are not supported. Functions and forms like seclink, other-doc, racketmodname, tech, and techlink provide higher-level interfaces for creating supported kinds of indirect links.
Changed in version 1.26 of package scribble-lib: Added link-render-style support.
struct
(struct index-element element (tag plain-seq entry-seq desc) #:extra-constructor-name make-index-element) tag : tag? plain-seq : (and/c pair? (listof string?)) entry-seq : (listof content?) desc : any/c
The entry-seq list must have the same length as plain-seq. It provides the form of each key to render in the final document.
The desc field provides additional information about the index entry as supplied by the entry creator. For example, a reference to a procedure binding can be recognized when desc is an instance of procedure-index-desc. See scribble/manual-struct for other typical types of desc values.
See also index.
struct
(struct multiarg-element (style contents) #:extra-constructor-name make-multiarg-element) style : element-style? contents : (listof content?)
struct
(struct traverse-element (traverse) #:extra-constructor-name make-traverse-element) traverse : element-traverse-procedure/c
struct
(struct delayed-element (resolve sizer plain) #:extra-constructor-name make-delayed-element) resolve : (any/c part? resolve-info? . -> . content?) sizer : (-> any/c) plain : (-> any/c)
The sizer field is a procedure that produces a substitute content for the delayed element for the purposes of determining the delayed element’s width (see element-width).
The plain field is a procedure that produces a substitute content when needed before the collect pass, such as when element->string is used before the collect pass.
struct
(struct part-relative-element (resolve sizer plain) #:extra-constructor-name make-part-relative-element) resolve : (collect-info? . -> . content?) sizer : (-> any/c) plain : (-> any/c)
The resolve function can call collect-info-parents to obtain a list of parts that enclose the element, starting with the nearest enclosing section. Functions like part-collected-info and collected-info-number can extract information like the part number.
struct
(struct collect-element element (collect) #:extra-constructor-name make-collect-element) collect : (collect-info . -> . any)
Unlike delayed-element or part-relative-element, the element remains intact (i.e., it is not replaced) by either the collect pass or resolve pass.
struct
(struct render-element element (render) #:extra-constructor-name make-render-element) render : (any/c part? resolve-info? . -> . any)
If a render-element instance is serialized (such as when saving collected info), it is reduced to a element instance.
struct
(struct collected-info (number parent info) #:extra-constructor-name make-collected-info) number : (listof part-number-item?) parent : (or/c #f part?) info : any/c
The length of the number list indicates the section’s nesting depth. Elements of number correspond to the section’s number, it’s parent’s number, and so on (that is, the section numbers are in reverse order):
A number value corresponds to a normally numbered section.
A non-empty string corresponds to a 'grouper section, which is shown as part of the combined section number only when it’s the first element.
A a list corresponds to a numberer-generated section string plus its separator string, where the separator is used in a combined section number after the section string and before a subsection’s number (or, for some output modes, before the title of the section).
For an unnumbered section, a #f is used in place of any number or lists element, while "" is used in place of all non-empty strings.
Changed in version 1.1 of package scribble-lib: Added (list/c string? string?) number items for numberer-generated section numbers.
struct
(struct target-url (addr) #:extra-constructor-name make-target-url) addr : path-string?
struct
(struct document-version (text) #:extra-constructor-name make-document-version) text : (or/c string? #f)
struct
(struct document-date (text) #:extra-constructor-name make-document-date) text : (or/c string? #f)
struct
(struct color-property (color) #:extra-constructor-name make-color-property) color : (or/c string? (list/c byte? byte? byte?))
When rendering to HTML, a color-property is also recognized for a block, part (and used for the title in the latter case)or cell in a table.
struct
(struct background-color-property (color) #:extra-constructor-name make-background-color-property) color : (or/c string? (list/c byte? byte? byte?))
struct
(struct table-cells (styless) #:extra-constructor-name make-table-cells) styless : (listof (listof style?))
If a cell style has a string name, it is used as an HTML class for the <td> tag or as a Latex command name.
The following are recognized as cell-style properties:
'border —
Draw a line around all sides of the cell. Borders along a shared edge of adjacent cells are collapsed into a single line. 'left-border, 'right-border, 'top-border, or 'bottom-border —
Draw a line along the corresponding side of the cell (with the same border collapsing as for 'border). color-property structure —
For HTML, applies a color to the cell content. background-color-property structure —
For HTML, applies a color to the background of the cell. attributes —
Provides additional HTML attributes for the cell’s <td> tag.
Changed in version 1.1 of package scribble-lib: Added color-property and
background-color-property support.
Changed in version 1.4: Added 'border, 'left-border,
'right-border, 'top-border,
and 'bottom-border support.
struct
(struct table-columns (styles) #:extra-constructor-name make-table-columns) styles : (listof style?)
For HTML table rendering, for each column that has a column-attributes property in the corresponding element of styles, the attributes are put into an HTML col tag within the table.
struct
(struct box-mode (top-name center-name bottom-name) #:extra-constructor-name make-box-mode) top-name : string? center-name : string? bottom-name : string?
procedure
name : string?
A boxing context starts with a table cell in a multi-column table, and the content of a block in a boxing context is also in a boxing context. If the cell’s content is boxable, then the content determines the width of the cell, otherwise a width is imposed. A paragraph with a #f style name is boxable as a single line; the 'wraps style name makes the paragraph non-boxable so that its width is imposed and its content can use multiple lines. A table is boxable when that all of its cell content is boxable.
To generate output in box mode, the box-mode property supplies Latex macro names to apply to the nested flow or paragraph content. The top-name macro is used if the box’s top line is to be aligned with other boxes, center-name if the box’s center is to be aligned, and bottom-name if the box’s bottom line is to be aligned. The box-mode* function creates a box-mode structure with the same name for all three fields.
A box-mode style property overrides any automatic boxed rendering (e.g., for a paragraph with style name #f). If a block has both a box-mode style property and a 'multicommand style property, then the Latex macro top-name, center-name, or bottom-name is applied with a separate argument for each of its content.
struct
(struct style (name properties) #:extra-constructor-name make-style) name : (or/c string? symbol? #f) properties : list?
procedure
(element-style? v) → boolean?
v : any/c
struct
(struct generated-tag () #:extra-constructor-name make-generated-tag)
procedure
(content->string content) → string?
content : content? (content->string content renderer p info) → string? content : content? renderer : any/c p : part? info : resolve-info?
If p and info arguments are not supplied, then a pre-“collect” substitute is obtained for delayed elements. Otherwise, the two arguments are used to force the delayed element (if it has not been forced already).
procedure
c : content?
procedure
e : block?
procedure
(part-number-item? v) → boolean
v : any/c
Added in version 1.1 of package scribble-lib.
procedure
v : any/c
procedure
(make-numberer step initial-value) → numberer?
step :
(any/c (listof part-number-item?) . -> . (values part-number-item? any/c)) initial-value : any/c
procedure
(numberer-step n parent-number ci numberer-values) →
part-number-item? hash? n : numberer? parent-number : (listof part-number-item?) ci : collect-info? numberer-values : hash?
The numberer? function returns #t if v is a numberer, or #f otherwise.
The make-numberer function creates a numberer. The step function computes both the current number’s representation and increments the number, where the “number” can be an arbitrary value; the initial-value argument determines the initial value of the “number”, and the step function receives the current value as its first argument and returns an incremented value as its second result. A numberer’s “number” value starts fresh at each new nesting level. In addition to the numberer’s current value, the step function receives the parent section’s numbering (so that its result can depend on the part’s nesting depth).
The numberer-step function is normally used by a renderer. It applies a numberer, given the parent section’s number, a collect-info value, and a hash table that accumulates numberer values at a given nesting layer. The collect-info argument is needed because a numberer’s identity is based on a generated-tag. The result of numberer-step is the rendered form of the current section number plus an updated hash table with an incremented value for the numberer.
Typically, the rendered form of a section number (produced by numberer-step) is a list containing two strings. The first string is the part’s immediate number, which can be combined with a prefix for enclosing parts’ numbers. The second string is a separator that is placed after the part’s number and before a subsection’s number for each subsection. If numberer-step produces a plain string for the rendered number, then it is not added as a prefix to subsection numbers. See also collected-info.
Added in version 1.1 of package scribble-lib.
struct
(struct link-render-style (mode) #:extra-constructor-name make-link-render-style) mode : (or/c 'default 'number)
The 'default and 'number modes represent generic hyperlink-style configurations that could make sense for various kinds of references. The 'number style is intended to mean that a specific number is shown for the reference and that only the number is hyperlinked. The 'default style is more flexible, allowing a more appropriate choice for the rendering context, such as using the target section’s name for a hyperlink in HTML.
Added in version 1.26 of package scribble-lib.
parameter
(current-link-render-style style) → void? style : link-render-style?
When a part has a link-render-style as one of its style properties, then the current-link-render-style parameter is set during the resolve pass and render pass for the part’s content.
Added in version 1.26 of package scribble-lib.
struct
(struct collect-info ( fp ht ext-ht ext-demand parts tags gen-prefix relatives parents) #:extra-constructor-name make-collect-info) fp : any/c ht : any/c ext-ht : any/c ext-demand : (tag? collect-info? . -> . any/c) parts : any/c tags : any/c gen-prefix : any/c relatives : any/c parents : (listof part?)
struct
(struct resolve-info (ci delays undef searches) #:extra-constructor-name make-resolve-info) ci : any/c delays : any/c undef : any/c searches : any/c
For a list that is an info tag, the interpretation of the second element of the list is effectively determined by the leading symbol, which classifies the key. However, a #f value as the second element has an extra meaning: collected information mapped by such info keys is not propagated out of the part where it is collected; that is, the information is available within the part and its sub-parts, but not in ancestor or sibling parts.
Note that every tag is an info key.
procedure
(collect-put! ci key val) → void?
ci : collect-info? key : info-key? val : any/c
procedure
(resolve-get p ri key) → any/c
p : (or/c part? #f) ri : resolve-info? key : info-key?
The result is #f if the no value for the given key is found. Furthermore, the search failure is recorded for potential consistency reporting, such as when racket setup is used to build documentation.
procedure
(resolve-get/ext? p ri key) →
any/c boolean? p : (or/c part? #f) ri : resolve-info? key : info-key?
procedure
(resolve-get/ext-id p ri key) →
any/c (or/c boolean? string?) p : (or/c part? #f) ri : resolve-info? key : info-key?
Added in version 1.1 of package scribble-lib.
procedure
(resolve-search dep-key p ri key) → void?
dep-key : any/c p : (or/c part? #f) ri : resolve-info? key : info-key?
The dep-key can be any value, but when it is a pair with #f as its car, then a failed search (possibly after re-builds) is not reported for the key.
Changed in version 1.43 of package scribble-lib: Added the convention to suppress reporting for a dep-key starts with #f.
procedure
(resolve-get/tentative p ri key) → any/c
p : (or/c part? #f) ri : resolve-info? key : info-key?
procedure
(resolve-get-keys p ri pred) → list?
p : (or/c part? #f) ri : resolve-info? pred : (info-key? . -> . any/c)
procedure
(part-collected-info p ri) → collected-info?
p : part? ri : resolve-info?
procedure
t : tag? ri : resolve-info?
procedure
(traverse-block-block b i) → block?
b : traverse-block? i : (or/c resolve-info? collect-info?)
procedure
(traverse-element-content e i) → content?
e : traverse-element? i : (or/c resolve-info? collect-info?)
(recursive-contract ((symbol? any/c . -> . any/c) (symbol? any/c . -> . any) . -> . (or/c block-traverse-procedure/c block?)))
(recursive-contract ((symbol? any/c . -> . any/c) (symbol? any/c . -> . any) . -> . (or/c element-traverse-procedure/c content?)))
6.3.6 HTML Style Properties
| (require scribble/html-properties) | |
| package: scribble-lib | |
struct
(struct attributes (assoc) #:extra-constructor-name make-attributes) assoc : (listof (cons/c symbol? string?))
struct
(struct alt-tag (name) #:extra-constructor-name make-alt-tag) name : (and/c string? #rx"^[a-zA-Z0-9]+$")
struct
(struct column-attributes (assoc) #:extra-constructor-name make-column-attributes) assoc : (listof (cons/c symbol? string?))
struct
(struct url-anchor (name) #:extra-constructor-name make-url-anchor) name : string?
struct
(struct hover-property (text) #:extra-constructor-name make-hover-property) text : string?
struct
(struct script-property (type script) #:extra-constructor-name make-script-property) type : string? script : (or/c path-string? (listof string?))
struct
(struct xexpr-property (before after) #:extra-constructor-name make-xexpr-property) before : xexpr/c after : xexpr/c
#lang scribble/base @(require scribble/core scribble/html-properties (only-in xml cdata)) @(define comments (xexpr-property (cdata #f #f "<!-- before -->") (cdata #f #f "<!-- after -->"))) Here is some @elem[#:style (style #f (list comments))]{content with comments around}.
Added in version 1.27 of package scribble-lib.
struct
(struct css-addition (path) #:extra-constructor-name make-css-addition)
path :
(or/c path-string? (cons/c 'collects (listof bytes?)) url? bytes?)
The path field can be a result of path->main-collects-relative.
struct
(struct css-style-addition (path) #:extra-constructor-name make-css-style-addition)
path :
(or/c path-string? (cons/c 'collects (listof bytes?)) url? bytes?)
struct
(struct js-addition (path) #:extra-constructor-name make-js-addition)
path :
(or/c path-string? (cons/c 'collects (listof bytes?)) url? bytes?)
struct
(struct js-style-addition (path) #:extra-constructor-name make-js-style-addition)
path :
(or/c path-string? (cons/c 'collects (listof bytes?)) url? bytes?)
struct
(struct body-id (value) #:extra-constructor-name make-body-id) value : string?
struct
(struct document-source (module-path) #:extra-constructor-name make-document-source) module-path : module-path?
More specifically, the section title is given the HTML attributes x-source-module and x-part-tag, plus x-part-prefixes if the section or enclosing sections declare tag prefixes, and x-source-pkg if the source is found within a package at document-build time. The scribble/manual style recognizes those tags to make clicking a title show cross-reference information.
Added in version 1.2 of package scribble-lib.
Changed in version 1.7: Added x-part-prefixes.
Changed in version 1.9: Added x-source-pkg.
struct
(struct html-defaults (prefix style extra-files) #:extra-constructor-name make-html-defaults)
prefix :
(or/c bytes? path-string? (cons/c 'collects (listof bytes?)))
style :
(or/c bytes? path-string? (cons/c 'collects (listof bytes?)))
extra-files :
(listof (or/c path-string? (cons/c 'collects (listof bytes?))))
struct
(struct head-extra (xexpr) #:extra-constructor-name make-head-extra) xexpr : xexpr/c
struct
(struct head-addition (xexpr) #:extra-constructor-name make-head-addition) xexpr : xexpr/c
Added in version 1.38 of package scribble-lib.
struct
(struct render-convertible-as (types) #:extra-constructor-name make-render-convertible-as) types : (listof (or/c 'png-bytes 'svg-bytes 'gif-bytes))
The alternatives in the types field are tried in order and the first one that succeeds is used in the html output.
Changed in version 1.34 of package scribble-lib: Added support for 'gif-bytes.
struct
(struct part-link-redirect (url) #:extra-constructor-name make-part-link-redirect) url : url?
struct
(struct link-resource (path) #:extra-constructor-name make-link-resource) path : path-string?
The file indicated by path is referenced in place when render<%> is instantiated with refer-to-existing-files as true. Otherwise, it is copied to the destination directory and potentially renamed to avoid conflicts.
struct
(struct install-resource (path) #:extra-constructor-name make-install-resource) path : path-string?
This style property is useful only when render<%> is instantiated with refer-to-existing-files as #f, and only when path does not match then name of any other file that is copied by the renderer to the destination.
6.3.7 Latex Style Properties
| (require scribble/latex-properties) | |
| package: scribble-lib | |
struct
(struct tex-addition (path) #:extra-constructor-name make-tex-addition)
path :
(or/c path-string? (cons/c 'collects (listof bytes?)) bytes?)
The path field can be a result of path->main-collects-relative.
struct
(struct latex-defaults (prefix style extra-files) #:extra-constructor-name make-latex-defaults)
prefix :
(or/c bytes? path-string? (cons/c 'collects (listof bytes?)))
style :
(or/c bytes? path-string? (cons/c 'collects (listof bytes?)))
extra-files :
(listof (or/c path-string? (cons/c 'collects (listof bytes?))))
(latex-defaults (list 'collects #"scribble" #"scribble-prefix.tex") (list 'collects #"scribble" #"scribble-style.tex") '())
See also scribble/latex-prefix.
struct
(struct latex-defaults+replacements latex-defaults (replacements) #:extra-constructor-name make-latex-defaults+replacements)
replacements :
(hash/c string? (or/c bytes? path-string? (cons/c 'collects (listof bytes?))))
For example if the replacements maps "scribble-load-replace.tex" to "my-scribble.tex", then the "my-scribble.tex" file in the current directory will we used in place of the standard scribble package inclusion header. Using "scribble-load-replace.tex" can disable the use of possibly-conflicting packages in the LaTeX output. The file (collection-file-path "scribble" "scribble.tex") contains a number of macros of the form \packageMathabx that will, by default, load the corresponding packages. Use a "scribble-load-replace.tex" replacement with content like #"\\renewcommand{\\packageMathabx}{\\relax}\n" to disable the loading of those packages.
struct
(struct command-extras (arguments) #:extra-constructor-name make-command-extras) arguments : (listof string?)
struct
(struct command-optional (arguments) #:extra-constructor-name make-command-optional) arguments : (listof string?)
Added in version 1.20 of package scribble-lib.
struct
(struct short-title (text) #:extra-constructor-name make-short-title) text : (or/c string? #f)
Added in version 1.20 of package scribble-lib.
struct
(struct table-row-skip (amount) #:extra-constructor-name make-table-row-skip) amount : string?
Added in version 1.33 of package scribble-lib.
6.4 Renderers
A renderer is an object that provides four main methods: traverse, collect, resolve, and render. Each method corresponds to a pass described in Structures And Processing, and they are chained together by the render function to render a document.
6.4.1 Rendering Driver
| (require scribble/render) | package: scribble-lib |
procedure
(render docs names [ #:render-mixin render-mixin #:dest-dir dest-dir #:helper-file-prefix helper-file-prefix #:keep-existing-helper-files? keep-existing-helper-files? #:prefix-file prefix-file #:style-file style-file #:style-extra-files style-extra-files #:extra-files extra-files #:image-preferences image-preferences #:xrefs xrefs #:info-in-files info-in-files #:info-out-file info-out-file #:redirect redirect #:redirect-main redirect-main #:directory-depth directory-depth #:quiet? quiet? #:warn-undefined? warn-undefined?]) → void? docs : (listof part?) names : (listof path-string?) render-mixin : (class? . -> . class?) = render-mixin dest-dir : (or/c #f path-string?) = #f helper-file-prefix : (or/c #f string?) = #f keep-existing-helper-files? : any/c = #f prefix-file : (or/c #f path-string?) = #f style-file : (or/c #f path-string?) = #f style-extra-files : (listof path-string?) = #f extra-files : (listof path-string?) = #f
image-preferences : (listof (or/c 'ps 'pdf 'png 'svg 'gif)) = null xrefs : (listof xref?) = null info-in-files : (listof path-string?) = null info-out-file : (or/c #f path-string?) = #f redirect : (or/c #f string?) = #f redirect-main : (or/c #f string?) = #f directory-depth : exact-nonnegative-integer? = 0 quiet? : any/c = #t warn-undefined? : any/c = (not quiet?)
The render-mixin argument determines the output format. By default, it is render-mixin from scribble/html-render.
The dest-dir argument determines the output directory, which is created using make-directory* if it is non-#f and does not exist already.
The helper-file-prefix, keep-existing-helper-files?, prefix-file, style-file, style-extra-files, and extra-files arguments are passed on to the render% constructor.
The image-preferences argument specified preferred formats for image files and conversion, where formats listed earlier in the list are more preferred. The renderer specified by render-mixin may not support all of the formats listed in image-preferences.
The xrefs argument provides extra cross-reference information to be used during the documents’ resolve pass. The info-in-files arguments supply additional cross-reference information in serialized form. When the info-out-file argument is not #f, cross-reference information for the rendered documents is written in serialized for to the specified file.
The redirect and redirect-main arguments correspond to the set-external-tag-path and set-external-root-url methods of render-mixin from scribble/html-render, so they should be non-#f only for HTML rendering.
The directory-depth arguments correspond to the set-directory-depth method of render-multi-mixin.
If quiet? is a false value, output-file information is written to the current output port.
If warn-undefined? is a true value, then references to missing cross-reference targets trigger a warning message on the current error port.
Changed in version 1.4 of package scribble-lib: Added the #:image-preferences argument.
Changed in version 1.40: Added the --keep-existing-helper-files?
initialization argument and
fixed --helper-file-prefix to work correctly
for HTML output.
6.4.2 Base Renderer
| (require scribble/base-render) | package: scribble-lib |
The mixin structure is meant to support document-specific extensions to the renderers. For example, the scribble command-line tool might, in the future, extract rendering mixins from a document module (in addition to the document proper).
See the "base-render.rkt" source for more information about the methods of the renderer. Documents built with higher layers, such as scribble/manual, generally do not call the render object’s methods directly.
|
method
(send a-render traverse srcs dests) → (and/c hash? immutable?)
srcs : (listof part?) dests : (listof path-string?) Performs the traverse pass, producing a hash table that contains the replacements for and traverse-blocks and traverse-elementss. See render for information on the dests argument.
method
(send a-render collect srcs dests fp [demand]) → collect-info?
srcs : (listof part?) dests : (listof path-string?) fp : (and/c hash? immutable?)
demand : (tag? collect-info? . -> . any/c) = (lambda (tag ci) #f) Performs the collect pass. See render for information on the dests arguments. The fp argument is a result from the traverse method.The demand argument supplies external tag mappings on demand. When the collect-info result is later used to find a mapping for a tag and no mapping is already available, demand is called with the tag and the collect-info. The demand function returns true to indicate when it adds information to the collect-info so that the lookup should be tried again; the demand function should return #f if it does not extend collect-info.
method
(send a-render resolve srcs dests ci) → resolve-info?
srcs : (listof part?) dests : (listof path-string?) ci : collect-info? Performs the resolve pass. See render for information on the dests argument. The ci argument is a result from the collect method.
method
srcs : (listof part?) dests : (listof (or/c path-string? #f)) ri : resolve-info? Produces the final output. The ri argument is a result from the render method.The dests provide names of files for Latex or single-file HTML output, or names of sub-directories for multi-file HTML output. If the dests are relative, they’re relative to the current directory; normally, they should indicates a path within the dest-dir supplied on initialization of the render% object.
If an element of dests is #f, then the corresponding position of the result list contains a string for rendered document. Some renderers require that dest contains all path strings.
method
(send a-render serialize-info ri) → any/c
ri : resolve-info? Serializes the collected info in ri.
method
(send a-render serialize-infos ri count doc) → list?
ri : resolve-info? count : exact-positive-integer? doc : part? Like serialize-info, but produces count results that together have the same information as produced by serialize-info. The structure of doc is used to drive the partitioning (on the assumption that ri is derived from doc).
method
(send a-render deserialize-info v ci [ #:root root-path]) → void? v : any/c ci : collect-info? root-path : (or/c path-string? false/c) = #f Adds the deserialized form of v to ci.If root-path is not #f, then file paths that are recorded in ci as relative to an instantiation-supplied root-path are deserialized as relative instead to the given root-path.
method
(send a-render get-defined ci) → (listof tag?)
ci : collect-info? Returns a list of tags that were defined within the documents represented by ci.
method
(send a-render get-defineds ci count doc)
→ (listof (listof tag?)) ci : collect-info? count : exact-positive-integer? doc : part? Analogous to serialize-infos: returns a list of tags for each of count partitions of the result of get-defined, using the structure of doc to drive the partitioning.
method
(send a-render get-external ri) → (listof tag?)
ri : resolve-info? Returns a list of tags that were referenced but not defined within the documents represented by ri (though possibly found in cross-reference information transferred to ri via xref-transfer-info).
method
(send a-render get-undefined ri) → (listof tag?)
ri : resolve-info? Returns a list of tags that were referenced by the resolved documents with no target found either in the resolved documents represented by ri or cross-reference information transferred to ri via xref-transfer-info.If multiple tags were referenced via resolve-search and a target was found for any of the tags using the same dependency key, then no tag in the set is included in the list of undefined tags.
constructor
(new render% [dest-dir dest-dir] [ [refer-to-existing-files refer-to-existing-files] [root-path root-path] [prefix-file prefix-file] [style-file style-file] [style-extra-files style-extra-files] [extra-files extra-files] [helper-file-prefix helper-file-prefix] [keep-existing-helper-files? keep-existing-helper-files?] [image-preferences image-preferences]]) → (is-a?/c render%) dest-dir : path-string? refer-to-existing-files : any/c = #f root-path : (or/c path-string? #f) = #f prefix-file : (or/c path-string? #f) = #f style-file : (or/c path-string? #f) = #f style-extra-files : (listof path-string?) = null extra-files : (listof path-string?) = null helper-file-prefix : (or/c path-string? #f) = #f keep-existing-helper-files? : any/c = #f
image-preferences : (listof (or/c 'ps 'pdf 'png 'svg 'gif)) = null Creates a renderer whose output will go to dest-dir. For example, dest-dir could name the directory containing the output Latex file, the HTML file for a single-file output, or the output sub-directory for multi-file HTML output.If refer-to-existing-files is true, then when a document refers to external files, such as an image or a style file, then the file is referenced from its source location instead of copied to the document destination.
If root-path is not #f, it is normally the same as dest-dir or a parent of dest-dir. It causes cross-reference information to record destination files relative to root-path; when cross-reference information is serialized, it can be deserialized via deserialize-info with a different root path (indicating that the destination files have moved).
The prefix-file, style-file, and style-extra-files arguments set files that control output styles in a formal-specific way; see Configuring Output for more information.
The extra-files argument names files to be copied to the output location, such as image files or extra configuration files.
The helper-file-prefix argument supplies a prefix that is used for any copied or generated files used by the main destination file. This prefix is not used for files listed in extra-files. If keep-existing-helper-files? is true, then any existing file that would otherwise be overwritten with a helper file is instead preserved, and the helper file is written to a different name, unless its content would be exactly the same as the existing file.
The image-preferences argument specified preferred formats for image files and conversion, where formats listed earlier in the list are more preferred. The renderer may not support all of the formats listed in image-preferences.
Changed in version 1.4 of package scribble-lib: Added the image-preferences initialization argument.
Changed in version 1.40: Added the --keep-existing-helper-files? initialization argument and fixed --helper-file-prefix to work correctly for HTML output.
method
(send a-render traverse parts dests) → (and/c hash? immutable?)
parts : (listof part?) dests : (listof path-string?)
method
(send a-render start-traverse parts dests fp) → (and/c hash? immutable?) parts : (listof part?) dests : (listof path-string?) fp : (and/c hash? immutable?)
method
(send a-render traverse-part p fp) → (and/c hash? immutable?)
p : part? fp : (and/c hash? immutable?)
method
(send a-render traverse-flow bs fp) → (and/c hash? immutable?)
bs : (listof block?) fp : (and/c hash? immutable?)
method
(send a-render traverse-block b fp) → (and/c hash? immutable?)
b : block? fp : (and/c hash? immutable?)
method
(send a-render traverse-nested-flow nf fp)
→ (and/c hash? immutable?) nf : nested-flow? fp : (and/c hash? immutable?)
method
(send a-render traverse-table t fp) → (and/c hash? immutable?)
t : table? fp : (and/c hash? immutable?)
method
(send a-render traverse-itemization i fp)
→ (and/c hash? immutable?) i : itemization? fp : (and/c hash? immutable?)
method
(send a-render traverse-compound-paragraph cp fp) → (and/c hash? immutable?) cp : compound-paragraph? fp : (and/c hash? immutable?)
method
(send a-render traverse-paragraph p fp)
→ (and/c hash? immutable?) p : paragraph? fp : (and/c hash? immutable?)
method
(send a-render traverse-content c fp) → (and/c hash? immutable?)
c : content? fp : (and/c hash? immutable?)
method
(send a-render traverse-target-element e fp) → (and/c hash? immutable?) e : target-element? fp : (and/c hash? immutable?)
method
(send a-render traverse-index-element e fp)
→ (and/c hash? immutable?) e : index-element? fp : (and/c hash? immutable?) These methods implement the traverse pass of document rendering. Except for the entry point traverse as described by as described at traverse in render<%>, these methods generally would not be called to render a document, but instead provide natural points to interpose on the default implementation.A renderer for a specific format is relatively unlikely to override any of these methods. Each method accepts the information accumulated so far and returns augmented information as a result.
method
(send a-render collect parts dests fp [demand]) → collect-info?
parts : (listof part?) dests : (listof path-string?) fp : (and/c hash? immutable?)
demand : (tag? collect-info? . -> . any/c) = (lambda (tag ci) #f)
method
(send a-render start-collect parts dests ci) → void?
parts : (listof part?) dests : (listof path-string?) ci : collect-info?
method
(send a-render collect-part p parent ci number init-sub-number init-sub-numberers)
→
part-number-item? numberer? p : part? parent : (or/c #f part?) ci : collect-info? number : (listof part-number-item?) init-sub-number : part-number-item? init-sub-numberers : (listof numberer?)
method
(send a-render collect-part-tags p ci number) → void? p : part? ci : collect-info? number : (listof part-number-item?)
method
(send a-render collect-flow bs ci) → void?
bs : (listof block?) ci : collect-info?
method
(send a-render collect-block b ci) → void?
b : block? ci : collect-info?
method
(send a-render collect-nested-flow nf ci) → void?
nf : nested-flow? ci : collect-info?
method
(send a-render collect-table t ci) → void?
t : table? ci : collect-info?
method
(send a-render collect-itemization i ci) → void?
i : itemization? ci : collect-info?
method
(send a-render collect-compound-paragraph cp ci) → void? cp : compound-paragraph? ci : collect-info?
method
(send a-render collect-paragraph p ci) → void?
p : paragraph? ci : collect-info?
method
(send a-render collect-content c ci) → void?
c : content? ci : collect-info?
method
(send a-render collect-target-element e ci) → void?
e : target-element? ci : collect-info?
method
(send a-render collect-index-element e ci) → void?
e : index-element? ci : collect-info? These methods implement the collect pass of document rendering. Except for the entry point collect as described at collect in render<%>, these methods generally would not be called to render a document, but instead provide natural points to interpose on the default implementation.A renderer for a specific format is most likely to override collect-part-tags, collect-target-element, and perhaps start-collect to set up and record cross-reference information in a way that is suitable for the target format.
method
(send a-render resolve parts dests ci) → resolve-info?
parts : (listof part?) dests : (listof path-string?) ci : collect-info?
method
(send a-render start-resolve parts dests ri) → void?
parts : (listof part?) dests : (listof path-string?) ri : resolve-info?
method
(send a-render resolve-part p ri) → void?
p : part? ri : resolve-info?
method
(send a-render resolve-flow bs enclosing-p ri) → void? bs : (listof block?) enclosing-p : part? ri : resolve-info?
method
(send a-render resolve-block b enclosing-p ri) → void? b : block? enclosing-p : part? ri : resolve-info?
method
(send a-render resolve-nested-flow nf enclosing-p ri) → void? nf : nested-flow? enclosing-p : part? ri : resolve-info?
method
(send a-render resolve-table t enclosing-p ri) → void? t : table? enclosing-p : part? ri : resolve-info?
method
(send a-render resolve-itemization i enclosing-p ri) → void? i : itemization? enclosing-p : part? ri : resolve-info?
method
(send a-render resolve-compound-paragraph cp enclosing-p ri) → void? cp : compound-paragraph? enclosing-p : part? ri : resolve-info?
method
(send a-render resolve-paragraph p enclosing-p ri) → void? p : paragraph? enclosing-p : part? ri : resolve-info?
method
(send a-render resolve-content c enclosing-p ri) → void? c : content? enclosing-p : part? ri : resolve-info? These methods implement the resolve pass of document rendering. Except for the entry point resolve as described at resolve in render<%>, these methods generally would not be called to render a document, but instead provide natural points to interpose on the default implementation.A renderer for a specific format is unlikely to override any of these methods. Each method for a document fragment within a part receives the enclosing part as an argument, as well as resolve information as ri to update.
method
parts : (listof part?) dests : (listof (or/c path-string? #f)) ri : resolve-info?
method
(send a-render render-one part ri dest) → any/c
part : part? ri : resolve-info? dest : (or/c path-string? #f)
method
(send a-render render-part p ri) → any/c
p : part? ri : resolve-info?
method
(send a-render render-part-content p ri) → any/c
p : part? ri : resolve-info?
method
(send a-render render-flow bs enclosing-p ri first-in-part-or-item?) → any/c bs : (listof block?) enclosing-p : part? ri : resolve-info? first-in-part-or-item? : boolean?
method
(send a-render render-block b enclosing-p ri first-in-part-or-item?) → any/c b : block? enclosing-p : part? ri : resolve-info? first-in-part-or-item? : boolean?
method
(send a-render render-nested-flow nf enclosing-p ri first-in-part-or-item?) → any/c nf : nested-flow? enclosing-p : part? ri : resolve-info? first-in-part-or-item? : boolean?
method
(send a-render render-table t enclosing-p ri first-in-part-or-item?) → any/c t : table? enclosing-p : part? ri : resolve-info? first-in-part-or-item? : boolean?
method
(send a-render render-auxiliary-table t enclosing-p ri) → any/c t : table? enclosing-p : part? ri : resolve-info?
method
(send a-render render-itemization i enclosing-p ri) → any/c i : itemization? enclosing-p : part? ri : resolve-info?
method
(send a-render render-compound-paragraph cp enclosing-p ri first-in-part-or-item?) → any/c cp : compound-paragraph? enclosing-p : part? ri : resolve-info? first-in-part-or-item? : boolean?
method
(send a-render render-intrapara-block p enclosing-p ri first-in-compound-paragraph? last-in-compound-paragraph? first-in-part-or-item?) → any/c p : paragraph? enclosing-p : part? ri : resolve-info? first-in-compound-paragraph? : boolean? last-in-compound-paragraph? : boolean? first-in-part-or-item? : boolean?
method
(send a-render render-paragraph p enclosing-p ri) → any/c p : paragraph? enclosing-p : part? ri : resolve-info?
method
(send a-render render-content c enclosing-p ri) → any/c c : content? enclosing-p : part? ri : resolve-info?
method
(send a-render render-other c enclosing-p ri) → any/c c : (and/c content? (not/c element?) (not/c convertible?)) enclosing-p : part? ri : resolve-info? These methods implement the render pass of document rendering. Except for the entry point render as described at render in render<%>, these methods generally would not be called to render a document, but instead provide natural points to interpose on the default implementation.A renderer for a specific format is likely to override most or all of these methods. The result of each method can be anything, and the default implementations of the methods propagate results and collect them into a list as needed. The value of current-output-port is set by render for each immediate part before calling render-one, so methods might individually print to render, or they might return values that are used both other methods to print. The interposition points for this pass are somewhat different than for other passes:
render-one is called by the render method on each immediate part in the list for its first argument.
render-auxiliary-table is called by the default render-block on any table that has the 'aux style property.
render-intrapara-block is called on blocks within a compound-paragraph, where the default implementation just chains to render% render-block.
render-other is called by the default implementation of render-content for any content that does not satisfy element? or convertible?.
6.4.3 Text Renderer
| (require scribble/text-render) | package: scribble-lib |
| ||
|
6.4.4 Markdown Renderer
| (require scribble/markdown-render) | |
| package: scribble-lib | |
| ||
|
```racket |
parameter
(current-markdown-link-sections) → boolean?
(current-markdown-link-sections enabled?) → void? enabled? : any/c
Added in version 1.31 of package scribble-lib.
6.4.5 HTML Renderer
| (require scribble/html-render) | package: scribble-lib |
| ||
|
constructor
(new render-mixin [ [search-box? search-box?]] ...superclass-args...) → (is-a?/c render-mixin) search-box? : boolean? = #f Specializes a render<%> class for generating HTML output. The arguments are the same as render<%>, except for the addition of search-box.If search-box? is #t and the document is created with scribble/manual, then it will be rendered with a search box, similar to this page. Note that the search-box? argument does not create the search page itself. Rather, it passes the search query to whatever page is located at search/index.html. The query is passed as an HTTP query string in the q field.
method
(send a-render set-external-tag-path url) → void?
url : string? Configures the renderer to redirect links to external documents via url, adding a tag query element to the end of the URL that contains the Base64-encoded, printed, serialized original tag (in the sense of link-element) for the link. The result of get-doc-search-url is intended for use as url.If the link is based on a cross-reference entry that has a document-identifying string (see load-xref and its #:doc-id argument), the document identifier is added as a doc query element, and a path to the target within the document is added as a rel query element.
method
(send a-render set-external-root-url url) → void?
url : string? Configures the renderer to redirect links to documents installed in the distribution’s documentation directory to the given URL, using the URL as a replacement to the path of the distribution’s document directory.
| ||
|
method
(send a-render-multi set-directory-depth depth) → void?
depth : exact-nonnegative-integer? Sets the depth of directory structure used when rendering parts that are own their own pages. A value of 0 is treated the same as 1.
6.4.6 Latex Renderer
| (require scribble/latex-render) | package: scribble-lib |
| ||
|
parameter
(extra-character-conversions) → (-> char? (or/c string? #f))
(extra-character-conversions convs) → void? convs : (-> char? (or/c string? #f))
Scribble already converts many special characters to the proper Latex commands. This parameter should be used in case you need characters it does not support yet.
6.4.7 PDF Renderer
| (require scribble/pdf-render) | package: scribble-lib |
| ||
|
| ||
|
Added in version 1.4 of package scribble-lib.
Added in version 1.19 of package scribble-lib.
Added in version 1.45 of package scribble-lib.
6.4.8 Contract (Blue boxes) Renderer
| (require scribble/contract-render) | |
| package: scribble-lib | |
| ||
|
method
(send an-override-render-mixin-multi render srcs dests ri) → void? srcs : (listof part?) dests : (listof path?) ri : render-info? In addition to doing whatever the super method does, also save the content of the blue boxes (rendered via a scribble/text-render renderer).It saves this information in three pieces in a file inside the dests directories called "blueboxes.rktd". The first piece is a single line containing a (decimal, ASCII) number. That number is the number of bytes that the second piece of information occupies in the file. The second piece of information is a hash that maps tag? values to a list of offsets and line numbers that follow the hash table. For example, if the hash maps '(def ((lib "x/main.rkt") abcdef)) to '((10 . 3)), then that means that the documentation for the abcdef export from the x collection starts 10 bytes after the end of the hash table and continues for 3 lines. Multiple elements in the list mean that that tag? has multiple blue boxes and each shows where one of the boxes appears in the file.
| ||
|
method
(send an-override-render-mixin-single render srcs dests ri) → void? srcs : (listof part?) dests : (listof path?) ri : render-info? Just like render, except that it saves the file "blueboxes.rktd" in the same directory where each dests element resides.
6.5 Decoding Text
| (require scribble/decode) | package: scribble-lib |
At the flow level, decoding recognizes a blank line as a paragraph separator. Blocks and paragraphs without blank lines in between are collected into a compound paragraph.
At the content level, decoding makes just a few special text conversions:
---: converted to 'mdash
--: converted to 'ndash
``: converted to 'ldquo, which is fancy open quotes: “
'': converted to 'rdquo, which is fancy closing quotes: ”
': converted to 'rsquo, which is a fancy apostrophe: ’
`: converted to 'lsquo, which is a fancy quote: ‘
Some functions decode a sequence of pre-flow or pre-content arguments using decode-flow or decode-content, respectively. For example, the bold function accepts any number of pre-content arguments, so that in
@bold{``apple''} |
the ``apple'' argument is decoded to use fancy quotes, and then it is bolded.
procedure
(pre-content? v) → boolean?
v : any/c
Pre-content is decoded into content by functions like decode-content and decode-paragraph.
Pre-flow is decoded into a flow (i.e., a list of blocks) by functions like decode-flow.
A pre-part sequence is decoded into a part by functions like decode and decode-part.
As a part is decoded, as long as the style for the part does not include the style property 'hidden or 'no-index, an entry is added to the document index for the part’s title.
Portions of lst are within a part are decoded using decode-flow.
Changed in version 1.25 of package scribble-lib: Added 'no-index support.
procedure
(decode-part lst tags title depth) → part?
lst : (listof pre-part?) tags : (listof string?) title : (or/c #f list?) depth : exact-nonnegative-integer?
procedure
(decode-flow lst) → (listof block?)
lst : (listof pre-flow?)
Portions of lst are within a compound paragraph are decoded using decode-compound-paragraph.
procedure
(decode-compound-paragraph lst) → block?
lst : (listof pre-flow?)
Portions of lst that are separated by blocks are decoded using decode-content.
procedure
(decode-paragraph lst) → paragraph?
lst : (listof pre-content?)
procedure
(decode-content lst) → list?
lst : (listof pre-content?)
procedure
(decode-elements lst) → list?
lst : (listof pre-content?)
procedure
(decode-string s) → (listof content?)
s : string?
procedure
(whitespace? v) → boolean?
v : any/c
struct
(struct title-decl (tag-prefix tags version style content) #:extra-constructor-name make-title-decl) tag-prefix : (or/c #f string?) tags : (listof string?) version : (or/c string? #f) style : style? content : content?
struct
(struct part-start (depth tag-prefix tags style title) #:extra-constructor-name make-part-start) depth : integer? tag-prefix : (or/c #f string?) tags : (listof string?) style : style? title : content?
struct
(struct part-index-decl (plain-seq entry-seq) #:extra-constructor-name make-part-index-decl) plain-seq : (listof string?) entry-seq : list?
struct
(struct part-collect-decl (element) #:extra-constructor-name make-part-collect-decl) element : (or/c element? part-relative-element?)
struct
(struct part-tag-decl (tag) #:extra-constructor-name make-part-tag-decl) tag : tag?
struct
(struct splice (run) #:extra-constructor-name make-splice) run : list?
procedure
(spliceof ctc) → flat-contract?
ctc : flat-contract?
procedure
(clean-up-index-string str) → string?
str : string?
6.6 Document Language
| #lang scribble/doclang2 | package: scribble-lib |
#:id names the top-level documentation binding. By default, this is doc.
#:post-process processes the body of the module after decode. By default, this is values.
#:begin prepends an additional sequence of expressions to the beginning of the module’s body outside of consideration for the document content. For example, the default configure-runtime submodule might be replaced using #:begin, because using #:exprs nests the replacement too deeply to work as an override. By default, this is the empty sequence ().
#:exprs prepends an additional sequence of expressions to the beginning of the module’s body, but after #:begin. By default, this is the empty sequence ().
#lang racket (module example scribble/doclang2 #:id doc #:post-process values #:exprs () "hello world, this is an example document") (require 'example) doc
#lang racket (module example scribble/doclang2 #:id documentation #:post-process (lambda (decoded-doc) (set! number-of-parts (length (part-parts decoded-doc))) decoded-doc) #:exprs ((title "My first expression!")) (require scribble/core scribble/base) (define number-of-parts #f) (provide number-of-parts) (section "part 1") "hello world" (section "part 2") "this is another document") (require 'example) number-of-parts documentation
Changed in version 1.41 of package scribble-lib: Added #:begin.
6.6.1 scribble/doclang
| #lang scribble/doclang | package: scribble-lib |
#lang racket (module* example scribble/doclang doc values () (require scribble/base) (provide (all-defined-out)) (define foo (para "hello again")) "hello world, this is an example document" (para "note the " (bold "structure"))) (module+ main (require (submod ".." example)) (printf "I see doc is: ~s\n\n" doc) (printf "I see foo is: ~s" foo))
6.7 Document Reader
| #lang scribble/doc | package: scribble-lib |
6.8 Cross-Reference Utilities
| (require scribble/xref) | package: scribble-lib |
procedure
(load-xref sources [ #:demand-source-for-use demand-source-for-use #:demand-source demand-source #:render% using-render% #:root root-path #:doc-id doc-id-str]) → xref? sources : (listof (-> (or/c any/c (-> list?))))
demand-source-for-use : (tag? symbol? -> (or/c (-> any/c) #f)) = (lambda (tag use-id) (demand-source tag))
demand-source : (tag? -> (or/c (-> any/c) #f)) = (lambda (tag) #f)
using-render% : (implementation?/c render<%>) = (render-mixin render%) root-path : (or/c path-string? false/c) = #f doc-id-str : (or/c path-string? false/c) = #f
Let source be a function in sources. The source function normally returns serialized information, info, which was formerly obtained from serialize-info in render<%>. The result of source can optionally be another function, which is in turn responsible for returning a list of infos. Finally, each info can be either serialized information, a #f to be ignored, or a value produced by make-data+root or make-data+root+doc-id, from which data part is used as serialized information, the root part overrides root-path for deserialization, and the doc-id part (if any) overrides doc-id-string to identify the source document.
The demand-source-for-use function can effectively add a new source to sources in response to a search for information on the given tag in the given rendering, where use-id is unique to a particular rendering request, a particular transfer (in the sense of xref-transfer-info), or all direct queries of the cross-reference information (such as through xref-binding->definition-tag). The demand-source-for-use function should return #f to indicate that no new sources satisfy the given tag for the given use-id.
The default demand-source-for-use function uses demand-source, which is provided only for backward compatibility. Since the demand-source function accepts only a tag, it is suitable only when the result of load-xref will only have a single use context, such as a single rendering.
Since the format of serialized information is specific to a rendering class, the optional using-render% argument accepts the relevant class. It defaults to HTML rendering, partly because HTML-format information is usable by other formats (including Latex/PDF and text).
If root-path is not #f, then file paths that are serialized as relative to an instantiation-supplied root-path are deserialized as relative instead to the given root-path, but a make-data+root result for any info supplies an alternate path for deserialization of the info’s data.
If doc-id-str is not #f, it identifies each cross-reference entry as originating from doc-id-str. This identification is used when a rendering link to the cross-reference entry as an external query; see the set-external-tag-path method of render-mixin.
Use load-collections-xref from setup/xref to get all cross-reference information for installed documentation.
Changed in version 1.1 of package scribble-lib: Added the #:doc-id argument.
Changed in version 1.34: Added the #:demand-source-for-use argument.
procedure
(xref-binding->definition-tag xref binding mode) → (or/c tag? false/c) xref : xref?
binding : mode : (or/c exact-integer? false/c)
The mode argument specifies the relevant phase level for the binding. The binding is specified in one of four ways:
If binding is an identifier, then identifier-binding is used with mode to determine the binding.
If binding is a two-element list, then the first element provides the exporting module and the second the exported name. The mode argument is effectively ignored.
If binding is a seven-element list, then it corresponds to a result from identifier-binding using mode.
If binding is a five-element list, then the first element is as for the two-element-list case, and the remain elements are as in the last four elements of the seven-element case.
If a documentation point exists in xref, a tag is returned, which might be used with xref-tag->path+anchor or embedded in a document rendered via xref-render. If no definition point is found in xref, the result is #f.
procedure
(xref-tag->path+anchor xref tag [ #:external-root-url root-url #:render% using-render%])
→
(or/c false/c path?) (or/c false/c string?) xref : xref? tag : tag? root-url : (or/c string? #f) = #f
using-render% : (implementation?/c render<%>) = (render-mixin render%)
If root-url is provided, then references to documentation in the main installation are redirected to the given URL.
The optional using-render% argument is as for load-xref.
procedure
(xref-render xref doc dest [ #:render% using-render% #:refer-to-existing-files? use-existing?]) → (or/c void? any/c) xref : xref? doc : part? dest : (or/c path-string? false/c)
using-render% : (implemenation?/c render<%>) = (render-mixin render%) use-existing? : any/c = (not dest)
If dest is #f, no file is written, and the result is an X-expression for the rendered page. Otherwise, the file dest is written and the result is #<void>.
The optional using-render% argument is as for load-xref. It determines the kind of output that is generated.
If use-existing? is true, then files referenced during rendering (such as image files) are referenced from their existing locations, instead of copying to the directory of dest.
procedure
(xref-transfer-info renderer ci xref) → void?
renderer : (is-a?/c render<%>) ci : collect-info? xref : xref?
procedure
(xref-index xref) → (listof entry?)
xref : xref?
struct
(struct entry (words content tag desc) #:extra-constructor-name make-entry) words : (and/c (listof string?) cons?) content : list? tag : tag? desc : any/c
The words list corresponds to index-element-plain-seq. The content list corresponds to index-element-entry-seq. The desc value corresponds to index-element-desc. The tag is the destination for the index link into the main document.
procedure
(data+root? v) → boolean?
v : any/c
procedure
(make-data+root data root) → data+root?
data : any/c root : (or/c #f path-string?)
procedure
(data+root+doc-id? v) → boolean?
v : any/c
procedure
(make-data+root+doc-id data root doc-id) → data+root+doc-id?
data : any/c root : (or/c #f path-string?) doc-id : string?
Added in version 1.1 of package scribble-lib.
6.9 Tag Utilities
| (require scribble/tag) | package: scribble-lib |
procedure
(make-section-tag name [ #:doc doc-mod-path #:tag-prefixes tag-prefixes]) → tag? name : string? doc-mod-path : (or/c module-path? #f) = #f tag-prefixes : (or/c #f (listof string?)) = #f
procedure
(make-module-language-tag lang) → tag?
lang : symbol?
A taglet is a value that can be combined with a symbol via list to form a tag, but that is not a generated-tag. A taglet is therefore useful as a piece of a tag, and specifically as a piece of a tag that can gain a prefix (e.g., to refer to a section of a document from outside the document).
procedure
(doc-prefix mod-path taglet) → taglet?
mod-path : (or/c #f module-path?) taglet : taglet? (doc-prefix mod-path extra-prefixes taglet) → taglet? mod-path : (or/c #f module-path?) extra-prefixes : (or/c #f (listof taglet?)) taglet : taglet?
If extra-prefixes is provided, then its content is added as a extra prefix elements before the prefix for mod-path is added. A #f value for extra-prefixes is equivalent to '().
If mod-path is #f, then taglet is returned without a prefix (except adding extra-prefixes, if provided).
procedure
(module-path-prefix->string mod-path) → string?
mod-path : module-path?
procedure
(module-path-index->taglet mpi) → taglet?
mpi : module-path-index?
The string form of the taglet is used as prefix in a tag to form cross-references into the document that is implemented by the module referenced by mpi.
procedure
(intern-taglet v) → any/c
v : any/c
procedure
(definition-tag->class/interface-tag definition-tag)
→ class/interface-tag? definition-tag : definition-tag?
Added in version 1.11 of package scribble-lib.
procedure
(class/interface-tag->constructor-tag class/interface-tag)
→ constructor-tag? class/interface-tag : class/interface-tag?
Added in version 1.11 of package scribble-lib.
procedure
(get-class/interface-and-method method-tag) →
symbol? symbol? method-tag : method-tag?
Added in version 1.11 of package scribble-lib.
procedure
(definition-tag? v) → boolean?
v : any/c
Added in version 1.11 of package scribble-lib.
procedure
(class/interface-tag? v) → boolean?
v : any/c
Added in version 1.11 of package scribble-lib.
procedure
(method-tag? v) → boolean?
v : any/c
Added in version 1.11 of package scribble-lib.
procedure
(constructor-tag? v) → boolean?
v : any/c
Added in version 1.11 of package scribble-lib.
6.10 Blue Boxes Utilities
| (require scribble/blueboxes) | package: scribble-lib |
procedure
(fetch-blueboxes-strs tag [ #:blueboxes-cache blueboxes-cache]) → (or/c #f (non-empty-listof string?)) tag : tag? blueboxes-cache : blueboxes-cache? = (make-blueboxes-cache #t)
The first string in the list describes the export (e.g. "procedure" when defproc is used, or "syntax" when defform was used to document the export).
procedure
(fetch-blueboxes-method-tags method-name [ #:blueboxes-cache blueboxes-cache]) → (listof method-tag?) method-name : symbol? blueboxes-cache : blueboxes-cache? = (make-blueboxes-cache #t)
Added in version 1.11 of package scribble-lib.
procedure
(make-blueboxes-cache populate? [ #:blueboxes-dirs blueboxes-dirs]) → blueboxes-cache? populate? : boolean? blueboxes-dirs : (listof path?) = (get-doc-search-dirs)
If populate? is #f, the cache is initially unpopulated, in which case it is filled in the first time the cache is passed to fetch-bluebxoes-strs. Otherwise, the cache is populated immediately.
The blueboxes-dirs argument is a list of directories that are looked inside for "blueboxes.rktd" files. The default value is only an approximation for where those files usually reside. See also get-rendered-doc-directories.
procedure
(blueboxes-cache? v) → boolean?
v : any/c
6.11 Extending and Configuring Scribble Output
Sometimes, Scribble’s primitives and built-in styles are insufficient to produce the output that you need. The cases in which you need to extend or configure Scribble fall into two groups:
You may need to drop into the back-end “language” of CSS or Latex to create a specific output effect. For this kind of extension, you will mostly likely attach a css-addition or tex-addition style property to style, where the addition implements the style name. This kind of extension is described in Implementing Styles.
You may need to produce a document whose page layout is different from the Racket documentation style. For that kind of configuration, you can run the scribble command-line tool and supply flags like --prefix or ++style, or you can associate a html-defaults or latex-defaults style property to the main document’s style. This kind of configuration is described in Configuring Output.
6.11.1 Implementing Styles
When a string is used as a style in an element, a multiarg-element, paragraph, table, itemization, nested-flow, or compound-paragraph, it corresponds to a CSS class for HTML output or a Latex macro/environment for Latex output. In Latex output, the string is used as a command name for a paragraph and an environment name for a table, itemization, nested-flow, or compound-paragraph; if the style has a 'command style property for a nested-flow or compound-paragraph, then the style name is used as a command instead of an environment; and if the style has a 'multicommand style property for a nested-flow, then the style name is used as a command with multiple arguments. In addition, for an itemization, the style string is suffixed with "Item" and used as a CSS class or Latex macro name to use for the itemization’s items (in place of \item in the case of Latex).
To add a mapping from your own style name to a CSS configuration, add a css-addition structure instance to a style’s style property list. To map a style name to a Latex macro or environment, add a tex-addition structure instance. A css-addition or tex-addition is normally associated with the style whose name is implemented by the addition, but it can also be added to the style for an enclosing part.
Scribble includes a number of predefined styles that are used by the exports of scribble/base. You can use them or redefine them. The styles are specified by "scribble.css" and "scribble.tex" in the "scribble" collection.
The styles used by scribble/manual are implemented by "racket.css" and "racket.tex" in the "scribble" collection. Other libraries, such as scriblib/autobib, similarly implement styles through files that are associated by css-addition and tex-addition style properties.
To avoid collisions with future additions to Scribble, start your style name with an uppercase letter that is not S. An uppercase letter helps to avoid collisions with macros defined by Latex packages, and future styles needed by scribble/base and scribble/manual will start with S.
For example, a Scribble document
#lang scribble/manual |
@(require scribble/core |
scribble/html-properties |
scribble/latex-properties) |
|
@(define inbox-style |
(make-style "InBox" |
(list (make-css-addition "inbox.css") |
(make-tex-addition "inbox.tex")))) |
|
@title{Quantum Pet} |
|
Do not open: @elem[#:style inbox-style]{Cat} |
combined with an "inbox.css" that contains
.InBox { |
padding: 0.2em; |
border: 1px solid #000000; |
} |
and an "inbox.tex" that contains
\newcommand{\InBox}[1]{\fbox{#1}} |
generates
Quantum Pet
Do not open: Cat
#lang scribble/base @(require scribble/core scribble/html-properties) @(define external-image (elem #:style (style #f (list (alt-tag "img") (attributes '((src . "http://racket-lang.org/icon.png"))))))) @external-image
renders as the the Racket logo at the url http://racket-lang.org/logo.png when producing html.
6.11.2 Configuring Output
The implementation of styles used by libraries depends to some degree on separately configurable parameters, and configuration is also possible by replacing style implementations. Latex output is more configurable in the former way, since a document class determines a set of page-layout and font properties that are used by other commands. The style-replacement kind of configuration corresponds to re-defining Latex macros or overriding CSS class attributes. When raco setup builds PDF documentation, it uses both kinds of configuration to produce a standard layout for Racket manuals; that is, it selects a particular page layout, and it replaces some racket/base styles.
Two kinds of files implement the two kinds of configuration:
A prefix file determines the DOCTYPE line for HTML output or the \documentclass configuration (and perhaps some addition package uses or other configurations) for Latex output.
The default prefix files are "scribble-prefix.html" and "scribble-prefix.tex" in the "scribble" collection.
A style file refines the implementation of styles used in the document—
typically just the “built-in” styles used by scribble/base. The default style files, "scribble-style.css" and "scribble-style.tex" in the "scribble" collection, change no style implementations.
For a given configuration of output, typically a particular prefix file works with a particular style file. Some prefix or style files may be more reusable. For now, reading the default files is the best way to understand how they interact. A prefix and/or style file may also require extra accomanying files; for example, a prefix file for Latex mode may require a corresponding Latex class file. The default prefix and style files require no extra files.
When rendering a document through the scribble command-line tool, use flags to select a prefix file, style file, and additional accompanying files:
Select the prefix file using the --prefix flag. (Selecting the prefix file also cancels the default list of accompanying files, if any.)
Replace the style file using the --style flag. Add additional style definitions and re-definitions using the ++style flag.
When using the scribble command-line utility, a document can declare its default style, prefix, and extra files through a html-defaults and/or latex-defaults style property. In particular, when using the scribble command-line tool to generate Latex or PDF a document whose main part is implemented with #lang scribble/manual, the result has the standard Racket manual configuration, because scribble/manual associates a latex-defaults style property with the exported document. The scribble/sigplan language similarly associates a default configuration with an exported document. As libraries imported with require, however, scribble/manual and scribble/sigplan simply implement new styles in a composable way.
Whether or not a document has a default prefix- and style-file configuration through a style property, the defaults can be overridden using scribble command-line flags. Furthermore, languages like scribble/manual and scribble/sigplan add a html-defaults and/or latex-defaults style property to a main-document part only if it does not already have such a property added through the #:style argument of title.
6.11.3 Base CSS Style Classes
The following renderings of "demo.scrbl" demonstrate all of the CSS style classes used by scribble/base forms and functions:
S1 All-Styles Document, Title in “H2” shows the default style in a single-page rendering without a search box.
M1 All-Styles Document, Title in “H2” shows the default style in a multi-page rendering without a search box.
S2 All-Styles Document, Title in “H2” shows the current manual style’s adjustments in a single-page rendering with a search box.
M2 All-Styles Document, Title in “H2” shows the current manual style’s adjustments in a multi-page rendering with a search box.
The style classes:
| maincolumn |
| Outer wrapper for all content in the main column. |
| main |
| Inner wrapper for all content in the main column, including navigation bars. |
|
|
|
|
| refpara |
| Outer wrapper for right-hand margin-note notes. |
| refparaleft |
| Outer wrapper for left-hand margin-note notes. |
| refelem |
| Outer wrapper for right margin-note* notes. |
| refelemleft |
| Outer wrapper for left-hand margin-note* notes. |
| refcolumn |
| Middle wrapper for right-hand margin-note and margin-note* notes. |
| refcolumnleft |
| Middle wrapper for left-hand margin-note and margin-note* notes. |
| refcontent |
| Inner wrapper for margin-note and margin-note* notes. |
|
|
|
|
| tocset |
| Groups table-of-contents panels: main and “on this page.” |
|
|
|
|
| tocview |
| Wraps the main (multi-page mode) or only (single-page mode) table-of-contents panel. |
| tocviewlist |
| A hierarchical layer of content in a main table-of-contents panel. |
| tocviewlisttopspace |
| With tocviewlist for the first layer. |
| tocviewtoggle |
| The always-visible name of a layer. |
| tocviewtitle |
| With tocviewtoggle for the first layer. |
| tocviewsublist |
| An item in a layer that has multiple items and more items before and after. |
| tocviewsublistonly |
| An item in a single-item layer. |
| tocviewsublisttop |
| The first item in a multi-item layer. |
| tocviewsublistbottom |
| The last item in a multi-item layer. |
| tocviewlink |
| Inner wrapper for an item in a layer when linked to a different page. |
| tocviewselflink |
| Inner wrapper for every item in a layer when linked to the same page. |
|
|
|
|
| tocsub |
| Wraps the “on this page” (multi-page mode only) table-of-contents panel. |
| tocsubtitle |
| Wraps the words “on this page”. |
| tocsublist |
| Inner table for the “on this page” panel. |
| tocsublinknumber |
| Number for an entry in an “on this page” panel. |
| tocsubseclink |
| Title for a section entry in an “on this page” panel. |
| tocsubnonseclink |
| Title for a non-section entry in an “on this page” panel that has some section links. |
| tocsublink |
| Title for a non-section entry in an “on this page” panel that has no section links. |
| toctoplink |
| Top-level entry in an inline (not the panel) table of contents. |
| toclink |
| Nested entry in an inline (not the panel) table of contents. |
|
|
|
|
| versionbox |
| Outer wrapper for version |
| version |
| Inner wrapper for version in the case of search box and/or navigation. |
| versionNoNav |
| Inner wrapper for version in the case of no search box and navigation. |
|
|
|
|
| SAuthorListBox |
| Outer wrapper for the author list. |
| SAuthorList |
| Inner wrapper for the author list. |
| author |
| Wrapper for an individual author. |
|
|
|
|
| navsettop |
| Wraps the top navigation bar (in multi-page mode or when a search bar is present). |
| navsetbottom |
| Wraps the bottom navigation bar (in multi-page mode or when a search bar is present). |
| navleft |
| Wraps left-side elements within a navigation bar. |
| navright |
| Wraps right-side elements within a navigation bar. |
| nonavigation |
| Disabled links within a navigation bar. |
| searchform |
| Outer wrapper for a search box within the top navigation bar. |
| searchbox |
| Inner wrapper for a search box within the top navigation bar. |
| nosearchform |
| Takes the place of an absent search box within the top navigation bar. |
|
|
|
|
| SSubSubSubSection |
| Deeply nested subsection (below <h5>). |
|
|
|
|
| SIntrapara |
| Used with <div> instead of <p> for a paragraph within a compound-paragraph. |
|
|
|
|
| SubFlow |
| For a nested-flow with no style name: no inset. |
| SCodeFlow |
| For a nested-flow with the 'code-inset style name: inset suitable for code. |
| SVInsetFlow |
| For a nested-flow with the 'vertical-inset style name: add space before and after suitable for code. |
| SCentered |
| For a nested-flow created by centered: horizontally centered. |
| SVerbatim |
| |
|
|
|
|
| boxed |
| For a table with the 'boxed style name: as a definition box. |
|
|
|
|
| compact |
| For an itemlist with the 'compact style name. |
|
|
|
|
| techoutside |
| Outer wrapper for a technical-term reference. |
| techinside |
| Inner wrapper for a technical-term reference. |
|
|
|
|
| indexlink |
| For an entry in the index. |
|
|
|
|
| stt |
| Fixed-width text. |
| sroman |
| Serif text. |
| ssanserif |
| Sans serif text. |
| slant |
| Oblique (as opposed to italic) text. |
| Smaller |
| Smaller text (as created by smaller). |
| Larger |
| Smaller text (as created by larger). |
| hspace |
| For whitespace produced by hspace. |
| nobreak |
| Disable link breaks. |
| badlink |
| Broken cross-reference. |
| plainlink |
| Hyperlink without an underline. |
In addition, the SIEHidden style class is built in to all Scribble HTML output to hide an element on Internet Explorer 6.
6.11.4 Manual CSS Style Classes
The following renderings of "demo-manual.scrbl" demonstrate all of the CSS style classes used by scribble/manual forms and functions in addition to the base style classes.
S1 Manual All-Styles Document shows the original style in a single-page rendering without a search box.
M1 Manual All-Styles Document shows the original style in a multi-page rendering without a search box.
S2 Manual All-Styles Document shows the current manual style’s adjustments in a single-page rendering with a search box.
M2 Manual All-Styles Document shows the current manual style’s adjustments in a multi-page rendering with a search box.
The style classes:
| RktSym |
| Identifiers with no for-label binding. |
| RktValLink |
| Identifier with for-label binding to a variable definition. |
| RktValDef |
| Definition site of a variable, normally combined with RktValLink. |
| RktStxLink |
| Identifier with for-label binding to a syntactic-form definition. |
| RktStxDef |
| Definition site of a syntactic form, normally combined with RktStxLink. |
| RktSymDef |
| Definition site of an identifier without binding (normally a mistake), combined with RktSym. |
| RktVar |
| Local variable or meta-variable. |
| RktRes |
| REPL result. |
| RktOut |
| Output written to the current output port. |
| RktErr |
| Output written to the current error port. |
| RktCmt |
| A comment in Racket code. |
| RktVal |
| A literal value in Racket code. |
| RktPn |
| Parentheses, keywords, and similar delimiters in Racket code. |
| RktRdr |
| Reader shorthands in Racket code, except for commas. |
| RktMeta |
| An unquoting comma in Racket code. |
| highlighted |
| Hilighlted code (via code:highlight in racketblock, for example). |
| RktIn |
| Foreground for literal characters written with litchar. |
| RktInBG |
| Background for literal characters written with litchar. |
| RktModLink |
| A module name linked to the module’s definition. |
| RktMod |
| A module name (normally RktModLink, instead). |
| RktKw |
| A “keyword;” not normally used. |
| RktOpt |
| Brackets for optional arguments (in function definitions). |
|
|
|
|
| RktBlk |
| Wrapper for multi-linke Racket code blocks. |
|
|
|
|
| defmodule |
| Module definition block. |
| RpackageSpec |
| Package specification within a module-definition block. |
|
|
|
|
| RBoxed |
| Definition block; always combined with boxed. |
| together |
| Table within a together grouping. |
| RBackgroundLabel |
| Wrapper for “procedure,” “syntax,” etc., backing in a definition box. |
| RBackgroundLabelInner |
| Wrapper within RBackgroundLabel. |
| RForeground |
| Wrapper for element to appear over a RBackgroundLabel. |
| prototype |
| Wrapper for a multi-line procedure-definition prototype. |
| argcontract |
| Wrapper for a multi-line argument contract and default value. |
| specgrammar |
| Wrapper for a grammar with a syntactic-form definition box. |
| inherited |
| Wrapper for a margin “inherited methods” table. |
| inheritedlbl |
| Wrapper for “Inherited methods:” and “from” labels. |
|
|
|
|
| leftindent |
| Left-indented block, such as form specsubform. |
| insetpara |
| Inset block. |
|
|
|
|
| Rfilebox |
| Wrapper for a file box (via filebox), |
| Rfiletitle |
| Outer wrapper for a file box title. |
| Rfilename |
| Inner wrapper for a file box title. |
| Rfilecontent |
| Wrapper for file box content. |
|
|
|
|
| SHistory |
| Wrapper for history paragraphs. |
|
|
|
|
| RBibliography |
| Wrapper for a bibliography section. |
6.11.5 Base Latex Macros
The "scribble.tex" Latex configuration includes several macros and environments that you can redefine to adjust the output style:
\preDoc —
called before the document content; the default does nothing, while the scribble/manual configuration enabled \sloppy. \postDoc —
called after the document content; the default does nothing. - A set of commands that control the basic set of Latex packages that are loaded:
\packageWasysym, defaults to \let\leftmoon\relax \let\rightmoon\relax \let\fullmoon\relax \let\newmoon\relax \let\diameter\relax \usepackage[nointegrals]{wasysym}
\packageTxfonts, defaults to \let\widering\relax \usepackage{newtxmath}
\packageColor, defaults to \usepackage[usenames,dvipsnames]{color}
\doHypersetup, defaults to \hypersetup{bookmarks=true,bookmarksopen=true,bookmarksnumbered=true}
\packageTocstyle, defaults to \IfFileExists{tocstyle.sty}{\usepackage{tocstyle}\usetocstyle{standard}}{}
\packageCJK, defaults to \IfFileExists{CJK.sty}{\usepackage{CJK}}{}
Changed in version 1.36: Added \packageTxfonts
Changed in version 1.37: Added \packageAmsmath; changed \packageWasysym to use nointegrals option; changed \packageTxfonts to load newtxmath. Note that documents could look different due to the new wasysym option and the inclusion of newtxmath. See racket/scribble#274 for examples.
\sectionNewpage —
called before each top-level section starts; the default does nothing, while the scribble/manual configuration uses \newpage to start each chapter on a new page. \SecRefLocal{}{}{} —
the first argument is a Latex label, the second argument is a section number, and the third argument is a section title. This macro is used by secref to reference a section (other than a document or top-level section within a document) that has a number and that is local to the current document. The default expands to \SecRef, passing along just the second and third arguments (so that the label is ignored). \SecRef{}{} —
like \SecRefLocal, but used when the referenced section is in a different document, so that no label is available. The default shows “section” followed by the section number (ignoring the title). The scribble/manual redefinition of this macro shows “§”, the section number, and the title in quotes. \ChapRefLocal{}{}{} and \ChapRef{}{} —
like \SecRefLocal and \SecRef, but for a top-level section within a document. The default implementation defers to \SecRefLocal or \SecRef. \PartRefLocal{}{}{} and \PartRef{}{} —
like \SecRefLocal and \SecRef, but for a top-level section within a document whose part has the 'grouper style property. The default \PartRef shows “part” followed by the section number (ignoring the title). \BookRefLocal{}{}{} and \BookRef{}{} —
like \SecRefLocal and \SecRef, but for a document (as opposed to a section within the document). The default \BookRef implementation shows the title in italic. \SecRefLocalUC{}{}{} and \SecRefUC{}{} —
like \SecRefLocal and \SecRef, but for Secref. The default \SecRefUC shows “Section” followed by the section number. \ChapRefLocalUC{}{}{} and \ChapRefUC{}{} —
like \ChapRefLocal and \ChapRef, but for Secref. The default \ChapRefUCimplementation defers to \SecRefUC. \PartRefLocalUC{}{}{} and \PartRefUC{}{} —
like \PartRefLocal and \PartRef, but for Secref. The default \PartRefUC shows “Part” followed by the section number. \BookRefLocalUC{}{}{} and \BookRefUC{}{} —
like \BookRefLocal and \BookRef, but for Secref. The default \BookRefUC defers to \BookRef. \SecRefLocalUN{}{}, \SecRefUCUN{}, \SecRefLocalUCUN{}{}, \SecRefUN{}, \PartRefLocalUN{}{}, \PartRefUN{}, \PartRefLocalUCUN{}{}, \PartRefUCUN{}, \BookRefLocalUN{}{}, \BookRefUN{}, \BookRefLocalUCUN{}{}, \BookRefUCUN{}, \ChapRefLocalUN{}{}, \ChapRefUN{}, \ChapRefLocalUCUN{}{}, and \ChapRefUCUN{} —
like \SecRefLocal, etc., but in the case that a section/part/chapter number is unavailable. The default implementation of \BookRefUN uses \BookRef with an empty first argument. The default \SecRefLocalUN expands to its second argument in quotes followed by “on page” as a \pageref using the first argument, while the default \SecRefUN expands to its only argument in quotes. The default \PartRef and \ChapRef variants expand to the corresponding \SecRef variant. \Ssection{}{}, \Ssubsection{}{}, \Ssubsubsection{}{}, \Ssubsubsubsection{}{}, \Ssubsubsubsubsection{}{} —
for a top-level section, a second-level section, etc., where the last variant is used for all sections that are deeper than four levels. The first argument corresponds to the optional argument to \section, which is used for the table of contents. \Ssectionstar{}, \Ssubsectionstar{}, \Ssubsubsectionstar{}, \Ssubsubsubsectionstar{}, \Ssubsubsubsubsectionstar{} —
like \Ssection, etc., but for unnumbered sections that are omitted from the table of contents. \Ssectionstarx{}{}, \Ssubsectionstarx{}, \Ssubsubsectionstarx{}{}, \Ssubsubsubsectionstarx{}{}, \Ssubsubsubsubsectionstarx{}{} —
like \Ssection, etc., but for unnumbered sections (that nevertheless appear in the table of contents). \Sincsection, \Sincsubsection, \Sincsubsubsection, \Sincsubsubsubsection, \Sincsubsubsubsubsection —
increments the section counter. \Spart{}{}, \Spartstar{}, \Spartstarx{}{}, \Sincpart —
like the section commands, but used for in place of \Ssection{}{}, \Ssectionstar{}, etc. for a part with the 'grouper style property. SInsetFlow environment —
for a nested-flow with the 'inset style name. SCodeFlow environment —
for a nested-flow with the 'code-inset style name. SVInsetFlow environment —
for a nested-flow with the 'vertical-inset style name. \SCodeBox{}, \SVInsetBox{} —
for a nested-flow with the 'code-inset or 'vertical-inset style name, respectively, and as the content of a table cell. The content is installed into a TeX box using \setbox1.
Additionally, the "racket.tex" Latex configuration includes several macros that you can redefine to adjust the output style of Racket code:
\SColorize{}{} —
Sets the color scheme of Racket code. Can be redefined to create black and white code. The first argument is the requested color, and the second argument is the text for that color. \SHyphen{} —
Enables or Disables the ability for identifiers and keywords in Racket code from being hyphenated. Defaults to enabled (for compatibility). Redefine to disable or change the hyphenation behavior. For example, to cause the text to overfill rather than hyphen, it can be redefined to: \renewcommand{\SHyphen}[1]{\mbox{#1}}. The first argument is an identifier or keyword inside of a code block.
6.11.6 Latex Prefix Support
| (require scribble/latex-prefix) | package: scribble-lib |
value
7 Running scribble
The scribble command-line tool (also available as raco scribble) runs a Scribble document and renders it to a specific format. Select a format with one of the following flags, where the output name fn is by default the document source name without its file suffix:
--html —
a single HTML page "fn.html", plus CSS sources and needed image files; this mode is the default if no format is specified --htmls —
multiple HTML pages (and associated files) in a "fn" directory, starting with "fn/index.html" --html-tree ‹n› —
HTML pages in a directory tree up to ‹n› layers deep; a tree of depth 0 is equivalent to using --html, and a tree of depth 1 is equivalent to using --htmls --latex —
LaTeX source "fn.tex", plus any needed additional files (such as non-standard class files) needed to run latex or pdflatex --pdf —
PDF "fn.pdf" that is generated via pdflatex --xelatex —
PDF "fn.pdf" that is generated via xelatex --lualatex —
PDF "fn.pdf" that is generated via lualatex --dvipdf —
PDF "fn.pdf" that is generated via latex, dvips, and pstopdf --latex-section ‹n› —
LaTeX source "fn.tex" plus additional ".tex" files to be included in the enclosing document’s preamble, where the enclosing document must use the UTF-8 input encoding and T1 font encoding; use 1 for ‹n› to make the rendered document a section, 2 for a subsection, etc. --text —
plain text in a single file "fn.txt", with non-ASCII content encoded as UTF-8 --markdown —
Markdown text in a single file "fn.md", with non-ASCII content encoded as UTF-8
Use --dest-name to specify a fn other than the default name, but only when a single source file is provided. Use the --dest flag to specify a destination directory (for any number of source files). Use --dest-base to add a prefix to the name of each support file that is generated or copied to the destination; the prefix can contain a directory path, and a non-directory ending element is used as a prefix on a support-file name. Use --keep-at-dest-base to avoid overwriting existing files with support files (but existing files are used when the content matches what would be written otherwise).
After all flags, provide one or more document sources, where each source declares a module. The module should either have a doc submodule that exports doc as a part, or it should directly export doc as a part. (The submodule is tried first, and the main module is not directly loaded or evaluated if the submodule can be loaded on its own.) Use --doc-binding to access an alternate exported name in place of doc.
When multiple documents are rendered at the same time, cross-reference information in one document is visible to the other documents. See Handling Cross-References for information on references that cross documents that are built separately.
Changed in version 1.4: Added --dvipdf.
Changed in version 1.18: Added --doc-binding.
Changed in version 1.19: Added --xelatex.
Changed in version 1.40: Added --keep-at-dest-base and
fixed --dest-base to work correctly
for HTML output.
Changed in version 1.45: Added --lualatex.
7.1 Extra and Format-Specific Files
Use the --style flag to specify a format-specific file to adjust the output style file for certain formats. For HTML (single-page or multi-page) output, the style file should be a CSS file that is applied after all other CSS files, and that may therefore override some style properties. For Latex (or PDF) output, the style file should be a ".tex" file that can redefine Latex commands. When a particular Scribble function needs particular CSS or Latex support, however, a better option is to use a css-addition or tex-addition style property so that the support is included automatically; see Extending and Configuring Scribble Output for more information.
In rare cases, use the --style flag to specify a format-specific base style file. For HTML (single-page or multi-page) output, the style file should be a CSS file to substitute for "scribble.css" in the "scribble" collection. For Latex (or PDF) output, the style file should be a ".tex" file to substitute for "scribble.tex" in the "scribble" collection. The --style flag is rarely useful, because the content of "scribble.css" or "scribble.tex" is weakly specified; replacements must define all of the same styles, and the set of styles can change across versions of Racket.
Use --prefix to specify an alternate format-specific start of the output file. For HTML output, the starting file specifies the DOCTYPE declaration of each output HTML file as a substitute for "scribble-prefix.html" in the "scribble" collection. For Latex (or PDF) output (but not Latex-section output), the starting file specifies the \documentclass declaration and initial \usepackage declarations as a substitute for "scribble-prefix.tex" in the "scribble" collection. See also html-defaults, latex-defaults, and Extending and Configuring Scribble Output.
For any output form, use the ++extra flag to add a needed file to the build destination, such as an image file that is referenced in the generated output but not included via image (which copies the file automatically).
7.2 Handling Cross-References
Cross references within a document or documents rendered together are always resolved. When cross references span documents that are rendered separately, cross-reference information needs to be saved and loaded explicitly. Cross-reference information is format-specific, but HTML-format information is usable for Latex (or PDF) or text rendering.
A Racket installation includes HTML-format cross-reference information for all installed documentation. Each document’s information is in a separate file, so that loading all relevant files would be tedious. The +m or ++main-xref-in flag loads cross-reference information for all installed documentation, so
scribble +m mine.scrbl
renders "mine.scrbl" to "mine.html" with cross-reference links to the Racket installation’s documentation. (The "racket-index" package must be installed to use +m/++main-xref-in.)
The ++xref-in flag loads cross-reference information by calling a specified module’s function. The setup/xref module provides load-collections-xref to load cross-reference information for all installed documentation, and +m or ++main-xref-in is just a shorthand for ++xref-in setup/xref load-collections-xref.
The --redirect-main flag for HTML output redirects links to the local installation’s documentation (not user-scope documentation) to a given URL, such as http://docs.racket-lang.org/. Beware that documentation links sometimes change (although Scribble generates HTML paths and anchors in a relatively stable way), so http://download.racket-lang.org/docs/version/html/ may be more reliable when building with an installation for version. The --redirect-main flag is ignored for non-HTML output.
The --redirect flag is like --redirect-main, except that it builds on the given URL to indicate a cross-reference tag that is more stable than an HTML path and anchor (in case the documentation for a function changes sections, for example), and it can generate redirected linked for documentation that is installed in user scope. The URL https://docs.racket-lang.org/local-redirect/index.html can work for these redirections.
For cross-references among documentation that is not part of the Racket installation, use --info-out to save information from a document build and use ++info-in to load previously saved information. For example, if "c.scrbl" refers to information in "a.scrbl" and "b.scrbl", then
builds "c.html" with cross-reference links into "a.html" and "b.html".
7.3 Selecting an Image Format
Use the ++convert ‹fmt› flag to select ‹fmt› as a preferred image format to use when rendering a document that includes values that can be converted to different image formats. The ‹fmt› argument can be pdf, ps, png, svg, or gif, but a renderer typically supports only a subset of those formats.
Use ++convert ‹fmt› multiple times to specify multiple preferred formats, where a ‹fmt› earlier in the command line take precedence over ‹fmt›s specified later.
For example, to generate Latex sources with images in Encapsulated PostScript format (so that the result works with latex instead of pdflatex), combine --latex with ++convert ps. To generate HTML pages with images converted to SVG format instead of PNG format, combine --html with ++convert svg.
Changed in version 1.4: Added ++convert support.
7.4 Passing Command-Line Arguments to Documents
When scribble loads and renders a document module, by default it sets current-command-line-arguments to an empty vector. Use the ++arg flag (any number of times) to add a string to current-command-line-arguments.
For example,
scribble ++arg --mode ++arg fast turtle.scrbl
causes (current-command-line-arguments) to return '#("--mode" "fast") while "turtle.scrbl" is loaded and rendered, which could affect the content that "turtle.scrbl" generates if it uses current-command-line-arguments.
Changed in version 1.1: Added the empty-vector default and ++arg flag.
7.5 Additional Options
--quiet —
suppress output-file and undefined-tag reporting --make or -y —
Enable automatic generation and update of compiled ".zo" files when loading document modules. Specifically, the result of (make-compilation-manager-load/use-compiled-handler) is installed as the value of current-load/use-compiled while loading a module. --doc-binding ‹id› —
render document provided as ‹id› instead of doc --errortrace —
enable errortrace
Changed in version 1.38: Added the --errortrace flag.
Changed in version 1.44: Added the --make/-y flag.